Skip to content

Tools

The tools, prompts and resources the novem MCP server lists to a client that has every scope, grouped by area.

AI-assisted, human-approvednovem uses AI to review and keep our documentation up to date.

This page is generated from the server's own tool definitions, so it matches what tools/list returns. The server offers 126 tools. A client sees the subset its scopes open; the MCP guide covers connecting a client.

Each tool carries two labels:

  • Behaviour: read-only tools only read; write tools only add, such as creating a resource or appending to one; destructive tools overwrite, delete, share, send or run something. Clients use this to decide what to ask you about.
  • Scope: the area on the consent screen that opens the tool. A tool marked any scope is available once you grant any area, and one marked always available needs none.

The description under each tool is the text the server gives the assistant.

General

general_add_resource_tagsAdd resource tags

writeany scope

Add one or more tags to a resource (plot, grid, mail, or doc) without replacing existing ones.

Description and parameters (3)
Add one or more tags to a resource (plot, grid, mail, or doc) without replacing existing ones.

Use the forms returned by general_list_resource_tags: bare system names
such as "fav", user tags such as "+sales", and categories such as "=finance".
A bare ordinary name such as "sales" adds "+sales". Use "+fav" to add a
user tag whose name matches a system tag. Names start with a letter and
contain only letters, numbers, hyphens, and underscores.

Returns:
    CallToolResult with status
ParameterTypeDescription
namerequiredstringResource name
tagsrequiredarray of stringList of tags to add
typerequiredstringResource type ("plot", "grid", "mail", or "doc")

general_api_GETRaw API GET

read-onlyany scope

Make a raw GET request to a Novem API endpoint.

Description and parameters (1)
Make a raw GET request to a Novem API endpoint.

The /v1 prefix is added automatically — do NOT include it in path.

Read novem://api-schema for valid path patterns before calling this tool.
The public reference for the API this tool calls is https://novem.io/docs/reference/api.

Call general_check_access() first to see which path prefixes you are
allowed to access. Omit path to list your visualisations at /v1/vis.
ParameterTypeDescription
pathstring
default ""
API path WITHOUT /v1 prefix, must start with / Correct: path="/vis/plots/my_plot/data" Incorrect: path="/v1/vis/plots/my_plot/data" (do not include /v1) Incorrect: path="vis/plots" (must start with /)

general_api_POSTRaw API POST

destructiveany scope

Update a Novem resource with new content via POST.

Description and parameters (2)
Update a Novem resource with new content via POST.

Read novem://api-schema for valid path patterns before calling this tool.
The public reference for the API this tool calls is https://novem.io/docs/reference/api.

Use this for updating resource data/configuration. For plot data updates,
the correct endpoint is /vis/plots/{name}/data (not /files/data.csv).

Common use cases:
    - Update plot data: POST /vis/plots/{name}/data (CSV as text/plain)
    - Update plot config: POST /vis/plots/{name}/config/title
    - Update mail content: POST /mails/{name}/content

To comment in a discussion thread, use general_post_comment instead.

Tips:
    - Read novem://api-schema before calling to discover valid paths
    - For plot data, use Content-Type: text/plain with CSV
    - Paths are case-sensitive

Examples:
    # Update plot with CSV data
    general_api_POST(
        path="/vis/plots/sales_dashboard/data",
        content="Date,Sales\n2024-01-01,100\n2024-01-02,150"
    )

    # Update plot title
    general_api_POST(
        path="/vis/plots/sales_dashboard/config/title",
        content="Q4 Sales Performance"
    )
ParameterTypeDescription
pathrequiredstringAPI path starting with / (e.g., "/vis/plots/my_plot/data") The /v1 prefix is added automatically.
contentrequiredstringContent to POST (string format)

general_api_PUTRaw API PUT

destructiveany scope

Create a new Novem resource via PUT.

Description and parameters (1)
Create a new Novem resource via PUT.

The /v1 prefix is added automatically — do NOT include it in path.

Read novem://api-schema for valid path patterns before calling this tool.
The public reference for the API this tool calls is https://novem.io/docs/reference/api.

Call general_check_access() to see which path prefixes you are allowed to write to.
To comment in a discussion thread, use general_post_comment instead.
A path that changes sharing requires user confirmation before the PUT.
ParameterTypeDescription
pathrequiredstringAPI path WITHOUT /v1 prefix, must start with / Correct: path="/vis/plots/my_new_plot" Incorrect: path="/v1/vis/plots/my_new_plot" (do not include /v1) Incorrect: path="vis/plots/my_new_plot" (must start with /)

general_check_accessCheck granted access

read-onlyalways available

Show the tools and API access granted to the authenticated user.

Description and parameters (0)
Show the tools and API access granted to the authenticated user.

No parameters.

general_delete_resourceDelete resource

destructiveany scope

Permanently delete a resource (plot, grid, mail, job, or repo) and all of its data/configuration.

Description and parameters (2)
Permanently delete a resource (plot, grid, mail, job, or repo) and all of its data/configuration.

Returns:
    CallToolResult with deletion status
ParameterTypeDescription
namerequiredstringResource name
typerequiredstringResource type ("plot", "grid", "mail", "job", or "repo")

general_delete_resource_varDelete resource variable

destructiveany scope

Delete a single variable from a resource (destructive — elicits confirmation).

Description and parameters (3)
Delete a single variable from a resource (destructive — elicits confirmation).

Doc references like `{/u/<user>/<t>/<name>/v/<var_name>}` will render as
plain text after the var is gone. Removing one var doesn't affect others
on the same resource.
ParameterTypeDescription
namerequiredstringResource name.
typerequiredstring'plot', 'grid', 'mail', 'doc', 'job', or 'repo'.
var_namerequiredstringVariable to delete.

general_describe_resourceDescribe resource

read-onlyany scope

One-shot synthesis of a resource — the *"tell me about this"* tool.

Description and parameters (3)
One-shot synthesis of a resource — the *"tell me about this"* tool.

Returns a compact summary suitable for starting a conversation about
any plot / doc / grid / mail you have access to (your own, public, or
shared-with-you). For deeper inspection of a specific piece (the JS,
the data, the full description, a thread) use `general_read_resource`
or `general_read_thread`.

Returns:
    - `identity`: id, type, title, summary, author, tags, shared_with, updated
    - `data_preview`: row/column counts, header, formats and a bounded sample
      (up to 5 rows × 20 columns, 256 characters per text cell)
    - `description_preview`: ~400-char plain-text preview of the description
    - `urls`: web / image / pdf URLs
    - `topics`: up to 5 most recent thread topics (creator + slug + size + timestamp)
ParameterTypeDescription
namerequiredstringResource id (the URL slug, e.g. 'ree_supply_gap' — NOT the shortname).
typerequiredstringplot | doc | grid | mail.
authorstring | nullOwner. Defaults to current user.

general_diff_historyDiff revisions

read-onlyany scope

Show what changed in one leaf between two revisions, as a unified diff — the `git diff`.

Description and parameters (6)
Show what changed in one leaf between two revisions, as a unified diff —
the `git diff`.

The defaults compare the previous revision (1) with the current one (0):
"what did the last write change". Read the diff before choosing between
fixing forward and general_restore_history; it costs a fraction of reading
both revisions in full.
ParameterTypeDescription
namerequiredstringThe resource id.
typerequiredstringOne of 'plot', 'doc', 'grid', 'mail', 'job', 'repo'.
partrequiredstringWhich leaf — same vocabulary as general_list_history.
revisioninteger | string
default 1
The older side. An index from general_list_history (0 = current, 1 = previous), a sha1 prefix, or an ISO 8601 timestamp (resolves to the newest revision at or before that instant).
againstinteger | string
default 0
The newer side, same forms. Default 0, the current content.
authorstring | nullOwner username for a resource shared with you. Omit for your own.

general_helpGet help topic

read-onlyalways available

Get documentation for Novem API topics and operations.

Description and parameters (1)
Get documentation for Novem API topics and operations.

Usage:
    general_help() - List all available topics
    general_help(topic='custom-plots') - Get documentation for that topic

Only returns documentation for modules accessible with your OAuth scopes.
ParameterTypeDescription
topicstring
default ""

general_list_historyList revisions

read-onlyany scope

List the retained revisions of one leaf of a resource — the `git log` of a plot's data, a doc's content or a job's schedule.

Description and parameters (4)
List the retained revisions of one leaf of a resource — the `git log` of a
plot's data, a doc's content or a job's schedule.

Call it before general_diff_history or general_restore_history, and
whenever you need to know what a leaf looked like before an edit. Revisions
come newest first: index 0 is the current content, 1 the one before it.
Only the last 10 revisions per leaf are kept, and a tool that rewrites the
whole leaf (docs_update_section, custom_plots_update_js_section) consumes
one revision per call, so check early rather than late.
ParameterTypeDescription
namerequiredstringThe resource id (the plot / doc / grid / mail / job / repo name).
typerequiredstringOne of 'plot', 'doc', 'grid', 'mail', 'job', 'repo'.
partrequiredstringWhich leaf. plot: data, js, css, deps. doc: content, css, theme. grid: layout, mapping, theme. mail: content, subject, theme. job: schedule, chains, type, filter. repo: type. Every type also takes name, description, summary, and any config leaf as 'config/<path>' (e.g. 'config/title'). Not covered: space file content, theme CSS, and repository code (that is git — use repos_list_commits and repos_diff).
authorstring | nullOwner username when the resource is shared with you rather than your own. Omit for your own resources.

general_list_inboxList notifications

read-onlyalways available

Notifications inbox — events you should know about, time-ordered.

Description and parameters (3)
Notifications inbox — events you should know about, time-ordered.

Distinct from `general_list_threads` (which is discussion-grouped per
resource). This is the event feed: new comments, mentions, job runs,
sharing actions, social, group invites — every notification the
platform has raised for your user.

Returns:
    Time-ordered list of notifications, each with actor, target, payload,
    and read/unread state.
ParameterTypeDescription
unread_onlyboolean
default false
True to filter to unread notifications only.
limitinteger
default 20
Max items to return after filtering (1-100, default 20).
event_classstring | nullOptional filter — 'comment', 'job', 'social', 'shared', 'invite', 'mention', 'reaction', etc.

general_list_resource_tagsList resource tags

read-onlyany scope

List all tags for a resource (plot, grid, mail, or doc).

Description and parameters (2)
List all tags for a resource (plot, grid, mail, or doc).

Returns:
    CallToolResult with list of tags
ParameterTypeDescription
namerequiredstringResource name
typerequiredstringResource type ("plot", "grid", "mail", or "doc")

general_list_resource_varsList resource variables

read-onlyany scope

List all live variables defined on a resource (via GraphQL — single round trip).

Description and parameters (2)
List all live variables defined on a resource (via GraphQL — single round trip).

Returns each var's id, value, about, format, type, threshold, and the
rendered text the doc parser would substitute.
ParameterTypeDescription
namerequiredstringResource name.
typerequiredstring'plot', 'grid', 'mail', 'doc', 'job', or 'repo'.

general_list_sharesList resource shares

read-onlyany scope

List every active share on a resource.

Description and parameters (2)
List every active share on a resource.

Returns the public flag and any group shares (org-group, user-group) along
with their permissions. Use this before adjusting shares so you can see
what's already in place.

Returns:
    Structured list of shares with target and permissions.
ParameterTypeDescription
namerequiredstringResource name.
typerequiredstringOne of plot | grid | mail | doc | job | repo | space.

general_list_threadsList discussion threads

read-onlyany scope

List discussion threads — your inbox view across all resources you have access to.

Description and parameters (2)
List discussion threads — your inbox view across all resources you have access to.

Use this as the catch-up / triage tool: *"any new activity on my plots,
docs, mails, etc.?"*. One call, sorted by `last_activity` desc.

To read the actual contents of a specific thread, use general_read_thread.

Returns:
    Aggregated discussion items, each summarising activity on one resource:
    - `vde_type`, `vde_shortname`, `vde_name`, `vde_url` — which resource
    - `author { username, name }` — resource owner
    - `total_topics`, `total_comments`, `total_likes`, `last_activity`
ParameterTypeDescription
modestring
default "mine"
'mine' (your resources + things shared with you, default) or 'top' (trending public discussions across the platform).
limitinteger
default 20
Max items (1-50, default 20).

general_post_commentPost comment

writeany scope

Post a comment in a discussion thread on a plot, doc, grid or mail.

Description and parameters (6)
Post a comment in a discussion thread on a plot, doc, grid or mail.

The comment is created with its text in one step. Find the thread first
with general_read_thread (call it without thread_path to list topics), and
read the thread before replying so the comment fits the conversation.
Mention a user with `@username`.

Returns:
    `comment_path` (pass it as reply_to to answer this comment), `comment`
    (the new comment's '@<you>~<slug>' name) and the topic `url`.
ParameterTypeDescription
namerequiredstringResource name (e.g. 'ree_supply_gap').
typerequiredstringOne of plot | doc | grid | mail.
thread_pathrequiredstringThe topic to comment in, as general_read_thread returns it (e.g. '@afa~flgsa01n').
messagerequiredstringThe comment text. Plain text or markdown, up to 10,000 characters.
authorstring | nullOwner of the resource. Defaults to the current user.
reply_tostring | nullOptional. The comment to reply to, as a path under the topic: '@bob~k2j9x0aa' for a top-level comment, or '@bob~k2j9x0aa/comments/@cy~p0q1r2s3' for a reply to a reply. Leave empty to comment on the topic itself.

general_read_resourceRead resource

read-onlyany scope

Read specific parts of a resource — the drill-down tool.

Description and parameters (4)
Read specific parts of a resource — the drill-down tool.

Fetches the REST aggregate at `/v1/u/<author>/<short>/<name>` then
returns only the requested parts. Use this after `general_describe_resource`
when you want to see the actual contents.

Returns:
    Object with requested parts as keys. Unrequested parts are omitted.
ParameterTypeDescription
namerequiredstringResource id (URL slug, e.g. 'ree_supply_gap').
typerequiredstringplot | doc | grid | mail.
authorstring | nullOwner. Defaults to current user.
partsarray of string | nullList of parts to return. Valid values: - 'identity' — full identity (id, title, author, tags, sharing, etc.) - 'description' — full HTML description - 'data' — data + metadata (columns, types, formats) - 'js' — custom plot JS source (plots only) - 'css' — custom plot CSS (plots only) - 'deps' — custom plot dependencies (plots only) - 'config' — full config tree (theme, layout, render, custom) - 'urls' — web/image/pdf URLs - 'all' — everything from the aggregate (heavy; use sparingly) Default is ['identity'] (lightest).

general_read_threadRead discussion thread

read-onlyany scope

Read discussion thread(s) on a resource — cross-namespace, recursive.

Description and parameters (4)
Read discussion thread(s) on a resource — cross-namespace, recursive.

Two modes:
- `thread_path=None`: list topic summaries on the resource (no message bodies).
- `thread_path='@<creator>~<slug>'`: read the full thread, walking nested
  replies into a flat tree. One return shape contains the topic message +
  all comments at all depths.

Works on any resource you can see — your own, public, or shared-with-you.

Returns:
    - List mode: `topics` array with creator/slug/name/size/last_modified.
    - Read mode: nested `topic` with `msg` + recursive `comments` tree.

To reply in a thread, use general_post_comment.
ParameterTypeDescription
namerequiredstringResource name (e.g. 'ree_supply_gap').
typerequiredstringOne of plot | doc | grid | mail.
authorstring | nullOwner of the resource. Defaults to the current user.
thread_pathstring | nullOptional. The thread path as it appears in the URL after `/c/` (e.g. '@afa~flgsa01n'). Leading `c/` or `threads/` is normalised away. Leave empty to just list topics.

general_remove_resource_tagsRemove resource tags

destructiveany scope

Remove one or more tags from a resource (plot, grid, mail, or doc).

Description and parameters (3)
Remove one or more tags from a resource (plot, grid, mail, or doc).

Accepts the tags exactly as general_list_resource_tags returns them:
user tags as "+sales", category tags as "=finance", and system tags
bare, such as "fav" or "like". A bare name removes the system tag of
that name if the resource has one, and the user tag "+<name>"
otherwise, so "sales" removes "+sales".

Returns:
    CallToolResult with status
ParameterTypeDescription
namerequiredstringResource name
tagsrequiredarray of stringList of tags to remove
typerequiredstringResource type ("plot", "grid", "mail", or "doc")

general_restore_historyRestore revision

destructiveany scope

Put one leaf back to an earlier revision — `git restore --source=<rev> -- <file>`.

Description and parameters (5)
Put one leaf back to an earlier revision — `git restore --source=<rev> -- <file>`.

The old bytes are written as a NEW revision: history stays append-only, the
restore shows up in general_list_history, and it can be undone the same
way. The write is conditional on the leaf still holding the content you
listed (If-Match); if someone wrote in between you get a precondition
error instead of overwriting their change — list again and retry. Restore
one leaf at a time: a tool call that wrote js, css and data produced three
separate leaf revisions. Use general_diff_history first when you are not
sure which revision you want.

Cannot undo: deleting a resource or a leaf (its history goes with it),
space file writes, theme CSS, mail sends, job runs.
ParameterTypeDescription
namerequiredstringThe resource id.
typerequiredstringOne of 'plot', 'doc', 'grid', 'mail', 'job', 'repo'.
partrequiredstringWhich leaf — same vocabulary as general_list_history.
revisionrequiredinteger | stringWhich revision to bring back: an index from general_list_history (1 = the one before the current), a sha1 prefix, or an ISO 8601 timestamp. 0 is the current content and a no-op.
authorstring | nullOwner username for a resource shared with you. Omit for your own.
read-onlyany scope

List and search your Novem resources.

Description and parameters (17)
List and search your Novem resources.

Default sort order: most-recently-updated first (the API returns items
ordered by `updated` descending; explicit ordering isn't configurable).

Returns:
    Structured response with:
    - `items` (single resource) or `buckets` (resource='all'): matched resources
    - `pagination`: limit / offset / total / mode info
    - `dropped_fields` (optional): fields you asked for but the server
      didn't recognise — present only when fields were dropped
    - `notes` (optional): runtime adjustments (limit capping, auto-pagination
      overriding limit, etc.) — present only when something was adjusted
    - `error_messages` (optional): API error messages, wrapped for inspection

Examples:
    # List your plots (minimal fields)
    general_search(resource="plots")

    # Get plots with social stats and tags
    general_search(resource="plots", fields=["id", "name", "social { likes favs }", "tags { id name }"])

    # Get job status info
    general_search(resource="jobs", fields=["id", "name", "schedule", "last_run_status", "run_count"])

    # Get mail recipients
    general_search(resource="mails", fields=["id", "name", "summary", "recipients { to { type recipient { id name } } }"])

    # List ALL users' plots
    general_search(resource="plots", author="*")

    # List plots updated in November 2025
    general_search(resource="plots", start_date="2025-11-01", end_date="2025-11-30")

    # List plots with specific tag
    general_search(resource="plots", tag="project-alpha")

    # Combine filters: your plots with tag, updated after date
    general_search(
        resource="plots",
        tag="sales",
        start_date="2025-11-01",
        filter_text="revenue"
    )

    # Search with text filter
    general_search(resource="plots", filter_text="sales")

    # Introspect available arguments for a resource
    general_search(resource="plots", introspect=True)

    # Search for a user by username (server-side filter)
    general_search(resource="users", query_args={"username": "steve"})

    # Get custom plots created in December 2025
    general_search(resource="plots", type_filter="custom", start_date="2025-12-01", end_date="2025-12-31", date_field="created")

    # Fetch specific plot by ID
    general_search(resource="plots", id="my-plot-id")

    # Filter groups by type
    general_search(resource="groups", query_args={"type": "org"})
ParameterTypeDescription
resourcerequiredstringResource type, or 'all' for cross-resource search. Singular or plural accepted — plot/plots, mail/mails, grid/grids, job/jobs, repo/repos, doc/docs, user/users, group/groups, tag/tags. (For your own user info use general_whoami.)
fieldsarray of string | nullFields to return. Validated against an allowlist; unrecognised fields are dropped and reported in `dropped_fields` of the response. Common: id, name, shortname, url, summary, type, public, created, updated Nested: social { likes favs }, tags { id name }, author { username } Jobs: schedule, last_run_status, last_run_time, run_count, job_steps, current_step Mails: recipients { to { type recipient { id name } } } Users: username, name Groups: parent_group Blocked (context efficiency): description Call with `introspect=True` to see the full list per resource.
limitinteger
default 20
Max items to return (1-50, default 20). Server caps at 50; capping is reported in `notes`. When client-side filters (filter_text, tag, date) trigger auto-pagination, `limit` does NOT cap the result set — a note explains.
offsetinteger
default 0
Skip first N items for pagination (default 0)
authorstring | nullFilter by author username. Use `scope` instead for the common cases; `author` is the low-level override.
scopestring | nullDiscovery scope. Higher-level than `author`: - 'mine' (default): your own resources - 'all': resources from all users - 'shared-with-me': resources shared with any group you're in (REST fan-out across your group memberships; supports a single resource type — `resource='all'` not allowed with this scope)
idstring | nullServer-side filter — fetch specific resource by id (the URL slug like 'example-map', NOT the shortname).
shortnamestring | nullServer-side filter — fetch specific resource by shortname (the system-generated short code in the URL, e.g. 'w9bON' for `/p/w9bON`). Useful for URL-to-resource lookups.
type_filterstring | nullClient-side filter by resource type. For plots, only "custom" is meaningful (MCP manages custom plots only).
filter_textstring | nullClient-side text filter (case-insensitive search across all fields)
sincestring | nullRelative-date shortcut for `start_date`. Accepts 'today', 'yesterday', or `<N><unit>` where unit is h/d/w/m. Examples: '7d' (last 7 days), '2w' (last 2 weeks), '1m' (last month). Ignored if `start_date` is also set.
start_datestring | nullFilter by date >= this (ISO format: "2025-11-01" or "2025-11-01T10:00:00")
end_datestring | nullFilter by date <= this (ISO format: "2025-12-31")
tagstring | nullFilter by tag id, as general_list_resource_tags returns it (e.g., "project-x" or "+project-x", "fav", "=finance"). A bare name matches the system tag or the "+" user tag. Single-resource scope. For a CROSS-resource tag search (plots + grids + mails + ...) use `general_search_by_tag`, or set `resource='all'`.
date_fieldstring
default "updated"
Which date field to filter on ("updated" or "created", default "updated")
introspectboolean
default false
If True, return available GraphQL arguments for this resource instead of data. Useful for discovering valid `query_args` keys.
query_argsobject | nullServer-side filters as dict (passed verbatim to GraphQL). Unknown keys produce a clear error in `error_messages`. Known keys (use introspect=True to discover more): - plots/grids/docs/mails/jobs/repos: shortname, id, author - users: {"username": "..."} - groups: {"name": "...", "type": "org|org_group|user_group", "parent_group": "..."} - tags: {"type": "..."}

general_search_by_tagSearch resources by tag

read-onlyany scope

Search for all resources (plots, grids, mails, jobs, repos, docs) by tag name.

Description and parameters (1)
Search for all resources (plots, grids, mails, jobs, repos, docs) by tag name.

The API automatically filters results based on your access permissions - you'll only
see resources you have access to.

Perfect for discovering project dependencies or finding all resources in a workflow.

Returns:
    CallToolResult with all resources matching the tag, organized by type
    (plots, grids, mails, jobs, repos, docs, etc.)

Examples:
    # Find all resources tagged with "q4-2024"
    general_search_by_tag(tag="q4-2024")

    # Find all resources in a project
    general_search_by_tag(tag="+project-alpha")
ParameterTypeDescription
tagrequiredstringTag name to search for (with or without '+' prefix, e.g., "project-x" or "+project-x"). Category tags keep their '=' prefix, e.g. "=finance".

general_search_docsSearch Novem documentation

read-onlyalways available

Search the Novem documentation and get back the pages to read.

Description and parameters (2)
Search the Novem documentation and get back the pages to read.

Search, then read: every hit carries `md_url`, the Markdown render of that
page. Fetch it to read the page in full — `snippet` is only the section
that matched, and `url` is the human-facing page with the section anchor.

Use this for questions about how Novem works: what a config key does, how
to share a plot, which chart types exist. Use `general_help` for guides to
the MCP tools in this server — those are a separate corpus.
ParameterTypeDescription
queryrequiredstringNatural-language question or keywords.
limitinteger
default 10
Max pages to return (1-50, default 10).

general_set_resource_sharingSet resource sharing

destructiveany scope

Share or unshare a resource with a group, an org-group, or the public.

Description and parameters (6)
Share or unshare a resource with a group, an org-group, or the public.

Four target shapes — pick the right one (full guide: general_help(topic='sharing')):

    'public'                  — view/use access to anyone with the link
    '@<user>'                 — share directly with a user (they must be visible to you)
    '+<org>~<group>'          — share with an org-group (you must be a member)
    '@<user>~<group>'         — share with a user-owned group (only the owner can share TO it)

Direct vs. user-group: '@bob' and '@bob~rw' share directly with the user bob;
'@bob~analysts' shares with bob's user-group 'analysts'. A second segment made
only of permission letters (r/w/d/x) always reads as a direct share, so a
personal group can't be named 'rw', 'rwd', etc.

Top-level orgs are NOT valid targets — `+novem` alone is rejected; use `+novem~<group>`.
A direct user share needs the target to be visible to you (public, connected, or a
co-member); an invisible or nonexistent user both return 404. Use `general_whoami()`
to discover which org-groups you have a role in. Membership in a user-group is not
enough to share to it; ownership is required.

Targets are pre-validated against your `general_whoami` output, so a group
you don't have a role in fails fast with a clear "not in your roles" error
rather than the misleading `404 path does not exist` the API returns
natively.

Optional permission suffix appended after the target: `~x` (default) | `~r` | `~rw` | `~rx` | `~rwx`.
Letters: x=view/use, r=use plus source read, w=write. `d` (delete) is refused: only the owner deletes. Either passed inline (`+acme~eng~rw`) or via the
`permissions` argument; inline wins if both are set. Public accepts x and r only.

**`include_embeds=True` (docs only):** also share/unshare every embedded
`{{ vis }}` / `{{ page ref: }}` plot/grid/mail inside the doc. One
confirmation prompt covers the doc plus every owned embed. Cross-user
embeds (e.g. `/u/other-user/p/foo`) are skipped — you can only share
resources you own. External-URL refs and broken refs are skipped too,
surfaced in the result.

**Embedding is NOT auto-sharing.** A viewer who can see your doc but not
its embedded plots sees "This visualisation is not available" for each
embed. Use `include_embeds=True` when publishing a doc with embeds
you've authored — the typical case.

After sharing, call `general_list_shares(name, type)` to verify the share landed.

Examples:
    general_set_resource_sharing(name='q4-revenue', type='plot', target='public')
    general_set_resource_sharing(name='q4-revenue', type='plot', target='@bob', permissions='rw')
    general_set_resource_sharing(name='roadmap', type='doc', target='+acme~engineering')
    general_set_resource_sharing(name='q1-report', type='doc',
                                 target='+acme~engineering', include_embeds=True)
    general_set_resource_sharing(name='nightly-etl', type='job',
                                 target='@alice~data-team', permissions='rw')
    general_set_resource_sharing(name='q4-revenue', type='plot',
                                 target='+acme~engineering', revoke=True)
ParameterTypeDescription
namerequiredstringResource name (lowercase alphanumeric, '-', '_').
typerequiredstringOne of plot | grid | mail | doc | job | repo | space.
targetrequiredstring'public' | '@<user>' | '+<org>~<group>' | '@<user>~<group>' (each optionally suffixed with `~<perms>`; slash is accepted as an ergonomic alias for `~`).
permissionsstring
default "x"
'x' (default) | 'r' | 'rw' | 'rx' | 'rwx'. Public accepts only x/r (or rx). An inline permission suffix takes precedence over this argument.
revokeboolean
default false
True to remove an existing share. For public, an inline suffix removes only those bits; bare 'public' removes the whole grant. The permissions argument is ignored on revoke.
include_embedsboolean
default false
When True and type='doc', also share/unshare every embedded plot/grid/mail in the doc with the same target+permissions. One confirmation covers the lot.

general_set_resource_varSet resource variable

destructiveany scope

Create or update a live variable on a Novem resource.

Description and parameters (8)
Create or update a live variable on a Novem resource.

Variables are small formatted data points (KPIs, returns, dates, labels)
attached to a plot/grid/mail/doc/job/repo. They are stored, formatted by
the server, and exposed at `/v1/u/<user>/<t>/<name>/v/<var>/txt`.

All fields are optional after the first set; subsequent calls only POST the
fields you supply. The PUT to create the var is idempotent (409 → treated
as already-exists, then field updates proceed).
ParameterTypeDescription
namerequiredstringResource name (e.g. 'q4-revenue-trend').
typerequiredstring'plot', 'grid', 'mail', 'doc', 'job', or 'repo'.
var_namerequiredstringVariable identifier (lowercase, alphanumeric + `-`/`_`, max 50 chars).
valuestring | nullRaw value (max 50 chars). For numbers pass the unscaled value, e.g. '0.041' for 4.1% (paired with format `+,.1%`). For text pass the verbatim string. Optional when updating to leave the value untouched.
aboutstring | nullDescription (max 250 chars).
formatstring | nullFormat string. Server-side default `+,.2%`. Recognised forms: - **Text**: `st` — display the raw value verbatim, no formatting. - **Numbers** (Python format mini-language): `.1f` → 22.5 (1 decimal float) `,.0f` → 21,725 (integer with thousands) `+,.1%` → +5.9% (signed percent, 1dp) `.1%` → 27.4% - **SI / scientific** (suffix `s`): `1s` → 1.2M; `2s` → 1.00m - **Money** (suffix `m`, optional currency before/after precision): `m` → 1,234.5; `.2m` → 1,234.50; `$2m` → $446.74; `.2m$` → 446.74$ - **Dates** (strftime): `%Y-%m-%d`, `%b %d, %Y`, etc.
var_typestring | nullOne of 'relative' | 'triangle' | 'plus_minus' | 'number' | 'text' | 'date'. - **`relative`**: prepends ↑/↓/→ based on sign vs threshold. - **`triangle`**: prepends ▲/▼/◆. - **`plus_minus`**: prepends +/−/=. - **`number`** / **`text`** / **`date`**: no indicator.
thresholdstring | nullReference point for `relative` (and similar) types' indicator and colour scaling. Default '0'.

general_whoamiWho am I

read-onlyalways available

Get current authenticated user information plus group / org memberships.

Description and parameters (0)
Get current authenticated user information plus group / org memberships.

Returns the authenticated username and the groups the user is a member of —
useful as a one-shot before sharing operations (groups become valid share
targets like `+<parent_group>~<slug>` or `@<owner>~<slug>`).

No parameters.

Custom plots

custom_plots_append_code_to_descriptionAppend code to plot description

writeCustom Plots

Append the custom JavaScript code to the plot description as a markdown code block.

Description and parameters (3)
Append the custom JavaScript code to the plot description as a markdown code block.

This tool fetches the current custom.js code and description, then appends the code
to the description. If a code section already exists (marked by "### Implementation Code"),
it can either replace it or append a duplicate section.

Useful for creating showcase plots where the implementation code is displayed alongside
the visualization.

Returns:
    CallToolResult with update status

Examples:
    # First time - append code to description
    custom_plots_append_code_to_description(plot_name="my-showcase-plot")

    # Update the code section after modifying JavaScript
    custom_plots_append_code_to_description(plot_name="my-showcase-plot")

    # Remove the code section
    custom_plots_append_code_to_description(plot_name="my-showcase-plot", remove=True)

    # Force append duplicate (rarely needed)
    custom_plots_append_code_to_description(
        plot_name="my-showcase-plot",
        replace_existing=False
    )
ParameterTypeDescription
plot_namerequiredstringName of the custom plot
replace_existingboolean
default true
If True, replaces any existing code section; if False, always appends a new code section even if one exists (default: True)
removeboolean
default false
If True, removes the code section from the description, restoring just the original description text (default: False)

custom_plots_append_rowsAppend plot data rows

writeCustom Plots

Append rows to a custom plot without replacing existing data.

Description and parameters (2)
Append rows to a custom plot without replacing existing data.

Provide one or more rows as CSV with a header row matching the existing column names.
Extra columns are dropped; missing columns are filled with empty values.
Use custom_plots_inspect_data first to confirm column names.

**CLI handoff:** there's no dedicated CLI "append" subcommand — for bulk
additions from a file on disk, compose the full CSV locally and re-push the
whole thing with **`novem -p <plot_name> -w data @data.csv`** instead of
looping calls to this tool. This tool is right for small in-conversation
additions (a few rows the agent constructed). See `general_help(topic='cli-handoff')`.
ParameterTypeDescription
plot_namerequiredstringName of the custom plot
rowsrequiredstringCSV string — header row followed by one or more data rows to append

custom_plots_check_overlapCheck plot label overlap

read-onlyCustom Plots

Diagnose whether a custom plot's SVG text labels visually overlap with other chart content (bars, points, axis lines, other labels, ...) at every share-target dimension — LinkedIn (4:5, 1:1), Instagram (4:5, 1:1, 9:16), X (16:9), OG, and iOS widgets (sm/md/lg).

Description and parameters (1)
Diagnose whether a custom plot's SVG text labels visually overlap with
other chart content (bars, points, axis lines, other labels, ...) at every
share-target dimension — LinkedIn (4:5, 1:1), Instagram (4:5, 1:1, 9:16),
X (16:9), OG, and iOS widgets (sm/md/lg).

Use this AFTER finishing a custom plot edit when you want to confirm the
chart still composes well across all output surfaces — author-time
layouts that look fine in the editor often collide on the smaller widget
canvases. Each entry includes the colliding text's CSS selector, the
fraction of the label covered, the compass direction of the overlap,
and a `collisions[]` array naming every individual element that
contributed (drill down to find which mark sits where).

EXPENSIVE: ~5-10s wall-clock. The create service renders the plot in
parallel at every share-target dimension and runs an in-page detector
in each — this is not free. Don't call after every small edit; call
once when you believe the design is settled, then again if you make
layout/typography changes.
ParameterTypeDescription
plot_namerequiredstringName of the custom plot to check.

custom_plots_createCreate custom plot

writeCustom Plots

Create a custom plot with user-provided JavaScript/CSS for visualization.

Description and parameters (13)
Create a custom plot with user-provided JavaScript/CSS for visualization.

Can also clone from an existing custom plot by providing source_plot parameter.

Write your JavaScript code directly — do NOT wrap it in a function.
The runtime automatically injects your code inside a draw function, so
the following parameters are already in scope:

Key parameters available in your code:
    - info.data: 2D array of data rows (refer to columns by index)
    - info.metadata.format[i].type: per-column type (datetime, us_number, int, text)
    - render.theme.colors[0..9]: theme palette — prefer over hardcoded hex
    - render.theme.text / .bg / .accent / .axisColor / etc.: chrome tokens
    - render.dark: boolean for dark mode
    - render.frac: DPI scale factor for text sizing
    - render.width / render.height: Container dimensions (use these, not window.innerWidth)
    - render.static: true when rendering PDF/PNG — gate animations on !render.static
    - node: DOM element to render into (use d3.select(node), not document.querySelector)

Lifecycle hooks — set these inside your draw code for smooth animated updates
instead of a full redraw on every data change:
    render.update = ({ info, render, node, prevInfo, prevRender, done }) => {
        // Called on data/config/dark-mode change. Animate freely. Call done() when complete.
    };
    render.resize = ({ info, render, node, prevInfo, prevRender, done }) => {
        // Called on dimension-only change. Snap to new size — no animation.
    };

Available libraries: D3.js v7, Observable Plot v0.6, Ramda

Before authoring from scratch, read the closest flagship example —
adapting one is faster and more reliable than re-inventing the
patterns (theme cascade, render.dark chrome, derived layout, lifecycle
hooks, etc.):
    - help(topic='custom-plots-examples')      ← index, pick by chart shape
    - help(topic='custom-plots-example-line')  ← multi-series time-series
    - help(topic='custom-plots-example-bar')   ← categorical bar w/ HTML tooltip
    - help(topic='custom-plots-example-map')   ← inlined Natural Earth basemap

For runtime API reference (what's in scope inside the draw function,
lint rules, lifecycle hook signatures):
    help(topic='custom-plots')

Writing the same chart for several plots? Publish it once as a module
plot instead — a repo builds an ES module and each plot names it as its
`config/type` (`@user/repo`), so one push updates every consumer:
    help(topic='module-plots')

The Novem API accepts up to 5 MB for `custom_js` and 5 MB for `data`
— effectively unbounded for any plot you'll actually author. Push
full bodies through this tool when an agent is producing the bytes.
Use the CLI only when the bytes are already on local disk and you'd
rather skip the model-context round-trip:
    `novem -p <name> -w config/custom/custom.js @plot.js`
    `novem -p <name> -w data @data.csv`
See `general_help(topic='cli-handoff')`.

Scaffolding: `data` and `custom_js` are both optional. If omitted, the
plot is created with renderable placeholders and the response carries a
warning naming the follow-up tool (`custom_plots_update_js` /
`custom_plots_update_data`). Use this when you want to scaffold the plot
first and fill it incrementally — common when you're still designing the
rendering code and don't want to block plot creation.

Returns:
    CallToolResult with plot URL and configuration status

Examples:
    # Create from scratch
    custom_plots_create(
        name="my-plot",
        data="x,y\n1,2\n3,4",
        custom_js="// visualization code"
    )

    # Clone from existing plot
    custom_plots_create(
        name="ethereum-chart",
        source_plot="bitcoin-chart",
        data="Date,Price\n2024-01-01,2500",
        title="Ethereum Price"
    )
ParameterTypeDescription
namerequiredstringPlot name (lowercase alphanumeric, '-', '_' only)
datastring | nullCSV data (newline-separated); first row treated as headers. Optional — if omitted, a placeholder ('placeholder\n0\n') is used. Always optional if source_plot provided (copied from source).
custom_jsstring | nullJavaScript rendering code. Optional — if omitted, a placeholder stub is used that renders '(placeholder)' text so the plot boots without errors. Always optional if source_plot provided (copied from source).
custom_cssstring | nullOptional CSS styling
custom_depsstring | nullOptional dependencies — newline-separated Novem registry specifiers, e.g. "d3@7\n@observablehq/plot@0.6". Not comma-separated; arbitrary URLs are not supported. See general_help(topic='custom-plots') for the available libraries.
source_plotstring | nullOptional plot to clone from. Use this to create a safe baseline before iterating — clone first, then experiment on the copy. Copies all code/config from source, then applies any explicit overrides
titlestring | nullOptional plot title
captionstring | nullOptional plot caption
descriptionstring | nullOptional detailed description displayed below the plot. Supports full Markdown including headers, lists, inline `code blocks`, links, bold/italic, etc.
summarystring | nullOptional one-sentence summary (max ~100 chars)
themestring
default "custom"
Theme name (default: 'custom')
copy_tagsboolean
default false
If True and source_plot provided, copy tags from source (default: False)
tagsarray of string | nullOptional tags (e.g., ["q4-2024", "sales"])

custom_plots_get_previewPreview plot

read-onlyCustom Plots

Get a rendered output file for a custom plot.

Description and parameters (3)
Get a rendered output file for a custom plot.

Returns an embedded resource URI — call resources/read with that URI to
get the binary. Mirrors `mails_get_preview` and `docs_get_preview` so the
LLM has a uniform preview verb across all visualization types. Pairs with
`custom_plots_test_render`, which returns fresh logs and the fetched static
PNG by default. Inspect its attached PNG instead of fetching that same
unchanged image again. Use this tool for a requested alternate format or
sharing size; default plot verification does not require those variants.

Pass `share_target` to render at a share-surface size (LinkedIn,
Instagram, X, og:image, iOS widget) instead of the default. Forces PNG
output; PDF doesn't have share flavors. Valid slugs: linkedin-45,
linkedin-11, instagram-45, instagram-11, instagram-916, x-169, some-og,
ios-widget-sm, ios-widget-md, ios-widget-lg.

Note: ASCII (`txt`) preview is not supported for custom plots — the
server-side renderer can't represent custom JS visualisations as text.
ParameterTypeDescription
plot_namerequiredstringName of the custom plot.
formatstring
default "png"
Output format — 'png' (default) or 'pdf'.
share_targetstring | nullOptional share-surface slug; forces PNG and overrides default dimensions. Omit for the standard preview.

custom_plots_inspect_cssInspect plot CSS

read-onlyCustom Plots

Fetch the full CSS styling for a custom plot.

Description and parameters (1)
Fetch the full CSS styling for a custom plot.

CSS files are typically small so the full content is returned. Use this before
calling custom_plots_update_css to review current styles before making changes.
ParameterTypeDescription
plot_namerequiredstringName of the custom plot to inspect

custom_plots_inspect_dataInspect plot data

read-onlyCustom Plots

Inspect a custom plot's CSV data with filtering and pagination. Prefer filtered reads over fetching all data.

Description and parameters (5)
Inspect a custom plot's CSV data with filtering and pagination. Prefer filtered reads over fetching all data.

- Use grep to find rows matching a pattern (e.g. grep="Norway")
- Use columns to restrict which columns are returned (e.g. columns=["date", "value"])
- Use offset + limit to page through data (default: first 50 rows)

The response always includes total_rows and has_more so you can plan follow-up reads.
Call custom_plots_update_data to replace all data, or custom_plots_append_rows to add rows.
ParameterTypeDescription
plot_namerequiredstringName of the custom plot
offsetinteger
default 0
Row offset for pagination (default: 0)
limitinteger
default 50
Max rows to return (default: 50)
columnsarray of string | nullColumn names to include (all if omitted)
grepstring | nullRegex to filter rows — only rows with a matching cell value are returned

custom_plots_inspect_interactionInspect real plot interactions

read-onlyCustom Plots

Inspect a plot in a real browser and exercise its visible controls.

Description and parameters (2)
Inspect a plot in a real browser and exercise its visible controls.

Use this to verify requested click/hover behavior after an interactive edit.
Batch up to six named actions, for example click Day, Week, Month and Year.
Click/select targets can be visible control labels; click/hover can target a
datum's SVG title (omit the hover target for a representative mark). A select action
also requires the option value. Omit actions to discover labels first.

Returns observed visible text, controls, SVG titles/positions before and
after each input, browser errors, and the final screenshot. Compare observed
values with the requested data semantics: a dispatched click or changed
screenshot alone does not prove correctness. An unchanged active control is
valid. Truncated observations cannot verify unreturned values.

Uses a fresh context for this authorized plot, 1200x675, with a 30-second
deadline. Local interactions do not save edits or publish the asset. Use
test_render for a static PNG; use this when actual interaction matters.
ParameterTypeDescription
plot_namerequiredstring
actionsarray of object | null

custom_plots_inspect_jsInspect plot JavaScript

read-onlyCustom Plots

Fetch custom JavaScript code from a plot. Prefer filtered reads to avoid flooding context.

Description and parameters (4)
Fetch custom JavaScript code from a plot. Prefer filtered reads to avoid flooding context.

- Use grep to locate a function, variable, or pattern (e.g. grep="drawBars")
- Use line_range to read a known section (e.g. line_range=(40, 80))
- Only omit both if you need to review the entire file (e.g. for an initial audit)

The response always includes total line count so you can plan follow-up line_range reads.
ParameterTypeDescription
plot_namerequiredstringName of the custom plot to inspect
grepstring | nullRegex pattern — returns matching lines plus context_lines around each match
line_rangearray of any | null(start, end) line numbers to fetch (1-indexed, inclusive)
context_linesinteger
default 3
Lines of context around grep matches (default: 3)

custom_plots_test_renderTest-render plot

read-onlyCustom Plots

Test rendering and SEE the static PNG together with fresh paginated log entries.

Description and parameters (4)
Test rendering and SEE the static PNG together with fresh paginated log entries.

This tool is useful for debugging custom plot rendering issues. It:
1. Snapshots the render log to find the newest existing entry (the high-water mark)
2. Triggers a server-side render by requesting the plot PNG
3. Returns ONLY log entries newer than the high-water mark (or a success message)
4. Allows scrolling through older entries if needed
5. Attaches the PNG fetched in step 2 (default). Inspect that image directly;
   a second read_resource for the same unchanged render is unnecessary.

The log format from the API (multi-line messages such as browser console
output continue on lines without a timestamp; those belong to the entry
above them):
    time                           path  severity  message
    -----------------------------  ----  --------  -----------------------------------------
    2026-01-05 17:59:56.469415+00  ./    info      Created new plot "example_plot".

Success Detection:
    If the render produced no new log entries, the tool reports that. This is a
    server-side STATIC render: code gated on `!render.static` (animations,
    transitions) never runs here, and a clean log does not prove the chart looks
    right. Confirm visually using the attached image. Static PNGs do not test
    live click/hover handlers. Images larger than 4 MiB are not attached.

Efficient debugging workflow:
    1. custom_plots_test_render(plot_name) - Check the rendered image and logs
    2. custom_plots_inspect_js(plot_name, grep="pattern") - Find the relevant code
    3. custom_plots_update_js_section(plot_name, ...) - Edit that section
    4. Inspect the attached PNG and diagnostic_entries. New informational
       logs alone are not a render failure; repeat only for a concrete defect.

Returns:
    CallToolResult with paginated log entries (newest first), pagination info,
    and statistics

Examples:
    # Get latest 10 log entries
    test_custom_plot_render(plot_name="bitcoin-bloomberg-pro")

    # Get next 10 older entries
    test_custom_plot_render(plot_name="bitcoin-bloomberg-pro", cursor="10")

    # Get latest 20 entries
    test_custom_plot_render(plot_name="bitcoin-bloomberg-pro", limit=20)

    # Efficient debugging cycle
    test_custom_plot_render("my-plot")  # Error: "lineColor is not defined"
    inspect_custom_plot_code("my-plot", grep="lineColor")  # Find the issue
    update_custom_plot_section("my-plot", "lineColor", "colors.line")  # Fix it
    test_custom_plot_render("my-plot")  # The render produced no new log entries
ParameterTypeDescription
plot_namerequiredstringName of the custom plot to test
cursorstring | nullOptional pagination cursor (offset). Use the nextCursor from previous response to fetch older log entries
limitinteger
default 10
Number of log entries to return (default: 10)
include_previewboolean
default true
Include the already-fetched PNG with the logs (default True). Set False for a logs-only debugging/pagination request.

custom_plots_updateUpdate custom plot

destructiveCustom Plots

Convenience tool to update any fields of a custom plot without recreating it.

Description and parameters (12)
Convenience tool to update any fields of a custom plot without recreating it.

Can update data, code (JS/CSS/deps), and metadata (title, caption, description, summary, theme, tags).
Use this for quick updates of multiple fields at once. For efficient single-field updates,
use the focused tools (custom_plots_update_data, custom_plots_update_js, etc.).

Returns:
    CallToolResult with update status

Examples:
    # Update multiple fields at once
    custom_plots_update(
        plot_name="my-plot",
        data="x,y\n1,2\n3,4",
        title="Updated Title",
        tags=["updated", "2024"]
    )

    # Copy from another plot
    custom_plots_update(
        plot_name="ethereum-chart",
        match_plot="bitcoin-chart",
        title="Ethereum Price"
    )

    # Update only JavaScript
    custom_plots_update(
        plot_name="my-plot",
        custom_js="// new code"
    )
ParameterTypeDescription
plot_namerequiredstringName of custom plot to update
datastring | nullOptional CSV data to update
custom_jsstring | nullOptional JavaScript rendering code
custom_cssstring | nullOptional CSS styling
custom_depsstring | nullOptional dependencies — newline-separated Novem registry specifiers, e.g. "d3@7\n@observablehq/plot@0.6". Not comma-separated; arbitrary URLs are not supported. See general_help(topic='custom-plots') for the available libraries.
match_plotstring | nullOptional plot name to copy from. If provided, copies all code/config from source, then applies any explicit overrides
titlestring | nullOptional plot title
captionstring | nullOptional plot caption
descriptionstring | nullOptional detailed description (supports full Markdown)
summarystring | nullOptional one-sentence summary
themestring | nullOptional theme name
tagsarray of string | nullOptional tags (e.g., ["q4-2024", "sales"])

custom_plots_update_cssReplace plot CSS

destructiveCustom Plots

Update the CSS styling for a custom plot (full replacement).

Description and parameters (2)
Update the CSS styling for a custom plot (full replacement).

**CLI handoff:** if the CSS is already on disk (or you've read it with the
`Read` tool), prefer **`novem -p <plot_name> -w config/custom/custom.css @plot.css`**.
The CLI streams the file directly — no context burn. Use this MCP tool only
when you're producing the CSS in-conversation, or when no shell is available.
See `general_help(topic='cli-handoff')`.

Returns:
    CallToolResult with update status
ParameterTypeDescription
plot_namerequiredstringName of the custom plot
custom_cssrequiredstringCSS styling code

custom_plots_update_dataReplace plot data

destructiveCustom Plots

Replace the CSV data for a custom plot (full replacement — not a patch).

Description and parameters (2)
Replace the CSV data for a custom plot (full replacement — not a patch).

Use custom_plots_inspect_data first to understand the current column structure
before submitting new data. The first row is treated as headers.

**CLI handoff:** if the CSV is already on disk (or you've read it with the
`Read` tool), prefer **`novem -p <plot_name> -w data @data.csv`** — the CLI
streams the file directly with no context burn. Use this MCP tool only when
you're producing the CSV in-conversation, or when no shell is available
(claude.ai web / iOS). See `general_help(topic='cli-handoff')`.
ParameterTypeDescription
plot_namerequiredstringName of the custom plot
datarequiredstringFull CSV content (newline-separated rows, first row = headers)

custom_plots_update_depsSet plot dependencies

destructiveCustom Plots

Update external dependencies for a custom plot.

Description and parameters (2)
Update external dependencies for a custom plot.

Returns:
    CallToolResult with update status
ParameterTypeDescription
plot_namerequiredstringName of the custom plot
custom_depsrequiredstringNewline-separated Novem registry specifiers, e.g. "d3@7\n@observablehq/plot@0.6". Not comma-separated; arbitrary URLs are not supported. See general_help(topic='custom-plots') for the available libraries.

custom_plots_update_descriptionSet plot description

destructiveCustom Plots

Update the description for a custom plot.

Description and parameters (2)
Update the description for a custom plot.

The description is displayed below the plot and supports full Markdown including
headers, lists, inline code blocks, links, bold/italic, etc.

Returns:
    CallToolResult with update status
ParameterTypeDescription
plot_namerequiredstringName of the custom plot
descriptionrequiredstringDetailed description (full Markdown supported)

custom_plots_update_jsReplace plot JavaScript

destructiveCustom Plots

Update the JavaScript code for a custom plot (full replacement).

Description and parameters (2)
Update the JavaScript code for a custom plot (full replacement).

For targeted edits, use custom_plots_update_js_section.

Before rewriting from scratch, check whether one of the flagship
examples already covers your chart shape — adapting one is faster
than re-deriving the patterns:
    - help(topic='custom-plots-examples')      ← index, pick by chart shape
    - help(topic='custom-plots-example-line')  ← multi-series time-series
    - help(topic='custom-plots-example-bar')   ← categorical bar w/ HTML tooltip
    - help(topic='custom-plots-example-map')   ← inlined Natural Earth basemap

**CLI handoff:** if the JS is already on disk (or you've read it with the
`Read` tool), prefer **`novem -p <plot_name> -w config/custom/custom.js @plot.js`**.
The CLI streams the file directly — no context burn. Use this MCP tool only
when you're producing the JS in-conversation, or when no shell is available.
See `general_help(topic='cli-handoff')`.

Returns:
    CallToolResult with update status
ParameterTypeDescription
plot_namerequiredstringName of the custom plot
custom_jsrequiredstringJavaScript rendering code

custom_plots_update_js_sectionEdit plot JavaScript sections

destructiveCustom Plots

Update one or more sections of custom plot JavaScript via string replacement.

Description and parameters (5)
Update one or more sections of custom plot JavaScript via string replacement.

Performs surgical edits without sending the full file. Fetches the file once,
applies all replacements, then writes back in a single request.

For a single edit provide old_code + new_code.
For multiple edits in one call provide sections — a list of {old_code, new_code} dicts.
All replacements are validated before any write — if one fails the file is not modified.

Each replacement fails if old_code is not found, or if it matches more than once
and replace_all is False.
ParameterTypeDescription
plot_namerequiredstringName of the custom plot to update
old_codestring | nullExact string to find (single-edit mode)
new_codestring | nullReplacement string (single-edit mode)
replace_allboolean
default false
Replace all occurrences instead of requiring uniqueness (default: False)
sectionsarray of object | nullList of {old_code, new_code, replace_all?} dicts for multi-edit mode

custom_plots_update_metadataSet plot metadata

destructiveCustom Plots

Update metadata fields for a custom plot (title, caption, description, summary, theme, tags).

Description and parameters (7)
Update metadata fields for a custom plot (title, caption, description, summary, theme, tags).

    This tool allows you to update plot metadata without modifying the visualization code.
    Only the fields you specify will be updated; others remain unchanged.

    Field descriptions:
        - title: Short plot title displayed at the top
        - caption: Brief caption or subtitle (typically 1-2 lines)
        - description: Detailed description displayed below the plot. Supports full Markdown
                      including headers, lists, inline `code blocks`, links, bold/italic, etc.
        - summary: One-sentence summary (max ~100 chars) for search/previews
        - theme: Theme name (e.g., 'custom', 'dark', 'light')
        - tags: List of tags for categorization/search

    Args:
        plot_name: Name of the custom plot to update
        title: Optional new title
        caption: Optional new caption
        description: Optional new description (full Markdown supported)
        summary: Optional new summary
        theme: Optional new theme name
        tags: Optional tags (e.g., ["q4-2024", "sales"])

    Returns:
        CallToolResult with update status

    Examples:
        # Update just the title
        update_custom_plot_metadata(
            plot_name="bitcoin-chart",
            title="Bitcoin Price History - 2024"
        )

        # Update description with Markdown
        update_custom_plot_metadata(
            plot_name="bitcoin-chart",
            description="""# Overview
This chart shows Bitcoin price trends over time.

## Key Metrics
- **High**: $68,000
- **Low**: $42,000
- **Average**: $55,000

Data source: CoinMarketCap"""
        )

        # Update multiple fields
        update_custom_plot_metadata(
            plot_name="sales-dashboard",
            title="Q4 2024 Sales Performance",
            summary="Quarterly sales analysis by region and product",
            caption="Updated January 2025"
        )
ParameterTypeDescription
plot_namerequiredstring
titlestring | null
captionstring | null
descriptionstring | null
summarystring | null
themestring | null
tagsarray of string | null

Documents

docs_append_contentAppend doc content

writeDocs

Append raw markdown at the very end of a doc — escape hatch.

Description and parameters (3)
Append raw markdown at the very end of a doc — escape hatch.

For adding a new section at the end, **prefer**
`docs_insert_section(position='end', new_content=...)` — it adds proper
section structure (with the right page-break boundaries), respects the
canonical blank-line spacing, and shows up cleanly in `docs_get_outline`.

Use `docs_append_content` only for free-form additions that don't fit a
section structure (e.g. extending the methodology callout at the end of
an existing trailing section).

**CLI handoff:** there's no dedicated CLI "append" subcommand for docs — if
you have the new content on disk and want to extend the doc, compose the full
body locally and re-push it with **`novem -d <doc_name> -w content @body.md`**.
This tool is right for small in-conversation additions. See
`general_help(topic='cli-handoff')`.
ParameterTypeDescription
doc_namerequiredstringDoc to append to.
contentrequiredstringMarkdown to append.
separatorstring
default "\n\n"
Inserted between existing content and new content. Defaults to a blank line.

docs_check_embedsCheck doc embeds

read-onlyDocs

Pre-publish lint for a Novem doc. Two passes:

Description and parameters (2)
Pre-publish lint for a Novem doc. Two passes:

1. **Ref validity** — every `{{ vis ref: ... }}` and `{{ page ref: ... }}`
   is resolved against the API. Output groups refs by status:
     - `ok`           — resource resolved.
     - `broken`       — API returned an error (404 most likely).
     - `unverifiable` — external URL or shortcode form we don't resolve.
     - `bad_format`   — could not parse the ref path at all.
2. **Block attribute lint** — walks every `{{ <block> ... }}` opener
   (`vis`, `page`, `para`, `callout`, `author`, …) and flags keys that
   aren't in the block's known set, unknown block names, and attributes on
   blocks that don't accept any. The Novem doc parser is lenient — unknown
   keys are silently dropped at render time — so this catch is critical
   before publish.

Theme: optionally also verifies the doc's `theme` exists. Set
`include_theme=False` to skip.

Saves the LLM from doing N round-trips to verify embeds before publish.
ParameterTypeDescription
doc_namerequiredstring
include_themeboolean
default true

docs_cloneClone doc

writeDocs

Clone an existing doc into a new doc, with optional overrides.

Description and parameters (8)
Clone an existing doc into a new doc, with optional overrides.

Useful for spinning up a sibling document that shares the source's theme/
structure but with new content — e.g. a Q1→Q2 quarterly report. Custom CSS
is preserved by default; pass an explicit empty string to drop it on the
clone, or a new CSS body to override.
ParameterTypeDescription
source_docrequiredstring
new_doc_namerequiredstring
contentstring | null
display_namestring | null
descriptionstring | null
themestring | null
doc_typestring | null
custom_cssstring | null

docs_createCreate doc

writeDocs

Create a new doc with markdown content and optional theme/metadata.

Description and parameters (7)
Create a new doc with markdown content and optional theme/metadata.
ParameterTypeDescription
doc_namerequiredstringUnique doc identifier (lowercase, no spaces; `-` and `_` allowed).
contentrequiredstringNovem markdown body. Supports YAML frontmatter (`--- title: ... theme: ... ---`), page breaks (`{{ page orient: portrait }}`), paragraph styling (`{{ para sz: l, st: b, al: center }} ... {{ /para }}`), callouts (`{{ callout type: info }} ... {{ /callout }}`), and embedded visualizations (`{{ vis ref: /u/user/p/plot, width: 100% }}`). Refer to `general_help(topic='docs')` for the full syntax. Begin published content with `{{ page }}`, `{{ frontpage }}` or `{{ tocpage }}`; preceding content is ignored except cascading headers/footers. Frontmatter creates no page.
display_namestring | nullHuman-readable doc name shown in the dashboard (POST /name).
descriptionstring | nullFree-text description (POST /description).
themestring | nullTheme reference. Use the built-in `novem`, `+org/yourorg` for an org theme, or any theme name available to the user. The theme cascades into every embedded plot/grid via CSS variables (`--novem-*`) and the `render.theme` JS object that custom plots receive.
doc_typestring | nullDoc layout type. Default is `doc`; consult `general_help(topic='docs')` for other supported values.
custom_cssstring | nullPer-doc CSS override applied on top of the theme. Use the `.novem--doc--*` hooks (page, header, footer, cover, content nodes) or re-route theme primitives like `--novem-accent`, `--novem-color-1`, etc. See `general_help(topic='docs')` "Per-doc Custom CSS" for the full hook list. Note: custom_css is ignored when theme='novem'; set theme='custom' or '+org/<name>' for it to take effect.

docs_delete_sectionDelete doc section

destructiveDocs

Delete a section by heading.

Description and parameters (4)
Delete a section by heading.

Returns the number of lines removed. Blank-line gap is collapsed to exactly
one blank line so the surrounding doc stays clean.
ParameterTypeDescription
doc_namerequiredstringDoc to edit.
headingrequiredstringHeading text of the section to remove (em-dash/hyphen and whitespace are normalized for matching).
levelinteger
default 2
Heading level (default 2 = `## `).
include_preceding_page_breakboolean
default true
Also remove the section's preceding `{{ page }}` block (default True). Set False to keep the page break so the section that follows takes its place on that page.

docs_get_configGet doc config

read-onlyDocs

Retrieve the configuration and metadata for a doc.

Description and parameters (1)
Retrieve the configuration and metadata for a doc.
ParameterTypeDescription
doc_namerequiredstring

docs_get_outlineGet doc outline

read-onlyDocs

Return the doc's outline: headings (level + text + line + page) and page breaks.

Description and parameters (3)
Return the doc's outline: headings (level + text + line + page) and page breaks.

The outline is a navigation map — much cheaper than reading the full body.
Use it to orient before edits: "what sections exist, on what pages, in what order?".

Also runs `_lint_doc_content` on the same fetched body and surfaces any
warnings in the result — so the LLM sees outstanding markdown issues every
time it navigates the doc, without an extra API call.

Pairs with `docs_get_section(heading=...)` to fetch a single section by name.
ParameterTypeDescription
doc_namerequiredstringDoc to outline.
include_pagesboolean
default true
Include page-break entries (default True).
max_levelinteger
default 6
Filter to headings at this level or shallower (default 6 = all).

docs_get_previewPreview doc

read-onlyDocs

Get a rendered output file for a doc.

Description and parameters (2)
Get a rendered output file for a doc.

Currently wired server-side: `pptx` and `pdf`. PNG, TXT, and ANSI exports
are planned but still stubbed in the API; calling them returns a clear error.
For both supported formats the tool returns an embedded resource URI —
call resources/read with that URI to get the binary.
ParameterTypeDescription
doc_namerequiredstringName of the doc.
formatstring
default "pptx"
Output format. One of 'pptx' (default) or 'pdf'.

docs_get_sectionRead doc section

read-onlyDocs

Fetch one section (by heading text) or one page (by index) from a doc.

Description and parameters (6)
Fetch one section (by heading text) or one page (by index) from a doc.

Provide exactly one of `heading=` or `page=`:
  - `heading='3 — Sector Attribution'` returns a section delimited by `## `
    headings (or set `level=` for `### ` etc.). When a `{{ page }}` block
    immediately precedes the heading, it is included by default
    (`include_preceding_page_break=True`).
  - `page=4` returns everything between the 4th `{{ page }}` boundary and the next.

Returns the raw markdown slice. Use this to read a focused chunk before
calling `docs_update_section` or `docs_replace`.
ParameterTypeDescription
doc_namerequiredstring
headingstring | null
pageinteger | null
levelinteger
default 2
include_preceding_page_breakboolean
default true
body_onlyboolean
default false
If True (and `heading=` was provided), return only the body text — no heading line, no preceding `{{ page }}` block, no leading or trailing blank lines. Round-trips with `docs_update_section(keep_heading=True, ...)`. Default False.

docs_grepSearch doc content

read-onlyDocs

Search a doc's markdown content for a regex (or literal string) pattern.

Description and parameters (6)
Search a doc's markdown content for a regex (or literal string) pattern.

Use this to find where a topic / phrase / variable / vis embed lives before
editing — much cheaper than fetching the full content. Returns each match
with line number, page number, and ±N lines of surrounding context.

Pairs naturally with `docs_get_section` (read the section the match is in)
and `docs_replace` (do a search-and-replace of the same pattern).
ParameterTypeDescription
doc_namerequiredstringDoc to search.
patternrequiredstringRegex by default; pass `regex=False` for a literal string match.
context_linesinteger
default 2
Number of context lines on each side (default 2).
max_matchesinteger
default 50
Cap the result list (default 50). Refine the pattern if hit.
regexboolean
default true
Treat `pattern` as a regex (default). False = literal substring.
case_sensitiveboolean
default false
Default False (case-insensitive match).

docs_insert_sectionInsert doc section

writeDocs

Insert a brand-new section into the doc.

Description and parameters (5)
Insert a brand-new section into the doc.

Insertion uses canonical blank-line splicing — exactly one blank line is
ensured on each side of the inserted block, so the doc stays clean.
ParameterTypeDescription
doc_namerequiredstringDoc to edit.
new_contentrequiredstringFull markdown for the new section. Should include the heading line and any leading `{{ page }}` block you want.
positionstring
default "after"
- `'before'` / `'after'`: place relative to `target_heading`. - `'start'`: place before the first `## ` section. - `'end'`: append after the last section.
target_headingstring | nullAnchor heading (required for before/after, ignored otherwise).
levelinteger
default 2
Heading level used to identify the target (default 2 = `## `).

docs_inspect_contentInspect doc content

read-onlyDocs

Inspect a doc's content without flooding the LLM with the full markdown.

Description and parameters (3)
Inspect a doc's content without flooding the LLM with the full markdown.
ParameterTypeDescription
doc_namerequiredstringDoc to inspect.
modestring
default "summary"
'summary' (default) returns frontmatter, headings, embeds, and counts — ideal for orienting before an edit. 'full' returns the raw markdown, capped at `max_chars`. 'head' returns only the first `max_chars` chars.
max_charsinteger
default 4000
Cap for full/head modes (default 4000).

docs_inspect_custom_cssInspect doc CSS

read-onlyDocs

Read the doc's per-doc custom CSS (the file at `/config/custom/custom.css`).

Description and parameters (2)
Read the doc's per-doc custom CSS (the file at `/config/custom/custom.css`).

Use this to inspect existing branding/style overrides before editing. The
response is capped at `max_chars` (default 8000) to keep the LLM context tidy.

For larger CSS bodies, fetch via the `docs://{doc_name}/css` resource instead.
ParameterTypeDescription
doc_namerequiredstring
max_charsinteger
default 8000

docs_move_sectionMove doc section

destructiveDocs

Reorder a section to a new position in the doc.

Description and parameters (6)
Reorder a section to a new position in the doc.

Heading match is normalized: em-dashes vs hyphens, varying whitespace, and
case differences all match. Round-trips are byte-stable thanks to canonical
blank-line splicing.
ParameterTypeDescription
doc_namerequiredstringDoc to edit.
headingrequiredstringSource section heading (the one to move).
target_headingstring | nullAnchor heading (required for 'before'/'after'). Omitted for 'start' and 'end'.
positionstring
default "after"
- `'before' <target>`: place source immediately before target. - `'after' <target>`: place source immediately after target. - `'start'`: move source to be the first `## ` section (after frontmatter and any cover content). - `'end'`: move source to be the last section.
levelinteger
default 2
Heading level for both source and target (default 2 = `## `).
include_preceding_page_breakboolean
default true
Include the source's preceding page break in the moved slice. Default True — sections that open their own page keep their own page after the move.

docs_replaceFind and replace in doc

destructiveDocs

Search-and-replace across a doc's markdown content.

Description and parameters (6)
Search-and-replace across a doc's markdown content.

Returns the count of replacements made. If zero matches, the doc is not modified.
Pairs naturally with `docs_grep` (preview matches first).
ParameterTypeDescription
doc_namerequiredstringDoc to edit.
findrequiredstringPattern to find. Literal by default; pass `regex=True` to use a Python regex.
replacerequiredstringReplacement string. With `regex=True`, supports `\1`, `\2`, etc.
regexboolean
default false
Treat `find` as a regex (default False).
countinteger | nullCap the number of replacements (default: replace all).
case_sensitiveboolean
default true
Default True.

docs_set_themeSet doc theme

destructiveDocs

Set the theme on a doc. The theme cascades through every embedded plot/grid: custom plots receive theme tokens via CSS variables (`var(--novem-*)`) and a `render.theme` JS object.

Description and parameters (2)
Set the theme on a doc. The theme cascades through every embedded plot/grid:
custom plots receive theme tokens via CSS variables (`var(--novem-*)`) and
a `render.theme` JS object.

Common theme values:
  - `novem` — built-in default
  - `+org/<orgname>` — your organisation's theme
  - any custom theme published to your account

Use `general_help(topic='docs')` for the full theme cascade explanation.
ParameterTypeDescription
doc_namerequiredstring
themerequiredstring

docs_spellcheckSpellcheck doc

read-onlyDocs

Spellcheck the prose of a doc and return a list of suspicious words.

Description and parameters (4)
Spellcheck the prose of a doc and return a list of suspicious words.

The checker walks the doc body and styled blocks (`{{ para }}` / callout /
preview) and skips: frontmatter, `{{ page }}` and `{{ vis }}` blocks, code
fences, inline code, link URLs, theme tokens, and the wrappers around
`[[text]]{fg: token}` / `[[ref: text]]` / `[[ftn: text]]` (the inline
text inside those is checked). Numeric tokens, single letters, and short
all-caps acronyms are dropped automatically.

Saves the LLM from reading the entire doc to look for typos.
ParameterTypeDescription
doc_namerequiredstringDoc to check.
languagestring
default "en"
Spellchecker language code (default 'en'; pyspellchecker also supports 'es', 'fr', 'pt', 'de', 'it', 'ru', 'ar', etc.).
custom_dictarray of string | nullOptional list of project-specific words to mark as known. Combined with the built-in NOVEM_CUSTOM_DICT (novem, vislib, MCP, PPTX, financial acronyms like AUM/CAGR/EBITDA, …).
max_wordsinteger
default 200
Cap on number of misspellings returned (default 200). Refine the custom dict if hit.

docs_swap_sectionsSwap doc sections

destructiveDocs

Atomically swap two sections.

Description and parameters (5)
Atomically swap two sections.

`heading_a` ends up where `heading_b` was, and vice versa. Page-break
blocks travel with each section, so each one keeps its own page after the
swap. Heading match is forgiving (em-dash/hyphen/whitespace/case-insensitive).

A single atomic operation — saves you from two `docs_move_section` calls
and the position-math gymnastics that go with them.
ParameterTypeDescription
doc_namerequiredstringDoc to edit.
heading_arequiredstringFirst section to swap.
heading_brequiredstringSecond section to swap.
levelinteger
default 2
Heading level for both (default 2 = `## `).
include_preceding_page_breakboolean
default true
Include each section's preceding page break in the swap. Default True.

docs_updateUpdate doc fields

destructiveDocs

Update one or more fields of an existing doc without recreating it. Only supplied fields are updated.

Description and parameters (7)
Update one or more fields of an existing doc without recreating it.
Only supplied fields are updated.

For surgical content edits, prefer `docs_update_content` (replace) or
`docs_append_content` (append). For just changing the theme,
`docs_set_theme` is the focused tool. For just changing the per-doc CSS,
use `docs_update_custom_css`.
ParameterTypeDescription
doc_namerequiredstring
contentstring | null
display_namestring | null
descriptionstring | null
themestring | null
doc_typestring | null
custom_cssstring | null

docs_update_contentReplace doc content

destructiveDocs

Replace the entire markdown body of a doc — escape hatch, not the primary edit tool.

Description and parameters (2)
Replace the entire markdown body of a doc — escape hatch, not the primary edit tool.

For partial edits, **prefer the section tools**:
  - `docs_update_section(keep_heading=True, ...)` to rewrite one section's body
  - `docs_replace(find=..., replace=...)` for search-and-replace
  - `docs_insert_section(...)` / `docs_delete_section(...)` / `docs_move_section(...)` for structure
  - `docs_swap_sections(...)` to swap two sections

Use `docs_update_content` only when you're rewriting the doc from scratch
or making changes that span the whole document and don't fit any section
pattern. It's the riskiest write path because a single typo replaces the
entire body.

**CLI handoff:** if the markdown body is already on disk (or you've read it
with the `Read` tool), prefer **`novem -d <doc_name> -w content @body.md`**.
The CLI streams the file directly — no context burn. Use this MCP tool only
when you're producing the markdown in-conversation, or when no shell is
available. See `general_help(topic='cli-handoff')`.
ParameterTypeDescription
doc_namerequiredstring
contentrequiredstring

docs_update_custom_cssReplace doc CSS

destructiveDocs

Replace the per-doc custom CSS — POSTs to `/config/custom/custom.css`.

Description and parameters (2)
Replace the per-doc custom CSS — POSTs to `/config/custom/custom.css`.

Use this for branded styling on top of the theme cascade: re-routing theme
primitives (e.g. `--novem-accent`, `--novem-color-1`), styling the page
chrome (`.novem--doc--page-header`, `.novem--doc--footer`), or adding
cover-page typography (`.novem--doc--cover-title`, `--cover-subtitle`).

Theme requirement: this CSS is only injected at render when the doc's
theme is `custom` or `+org/<name>`. The built-in `novem` theme intentionally
ignores it — set the theme accordingly with `docs_set_theme` if needed.

See `general_help(topic='docs')` "Per-doc Custom CSS" for the full hook
list (page structure, cover, content nodes, layout vars, data attrs).

The API accepts large bodies. Push CSS through this tool when an
agent is producing it; reach for the CLI only when the CSS is
already on local disk:
    `novem -d <doc_name> -w config/custom/custom.css @doc.css`
See `general_help(topic='cli-handoff')`.
ParameterTypeDescription
doc_namerequiredstring
custom_cssrequiredstring

docs_update_sectionUpdate doc section

destructiveDocs

Replace one section's body in place, identified by its heading.

Description and parameters (6)
Replace one section's body in place, identified by its heading.

The new body should include the heading line itself (e.g. `## 3 — New Heading`)
if you want to keep or change the heading. The section is delimited by the
next heading at the same or higher level (or end of doc). Any preceding
`{{ page }}` block is included by default and replaced as part of the slice.

Pairs with `docs_get_section` (read the current body first).
ParameterTypeDescription
doc_namerequiredstringDoc to edit.
headingrequiredstringHeading text (whitespace and em-dashes are normalized for matching).
new_contentrequiredstringFull markdown for the new section. If `keep_heading=False` (default), include the heading line and any preceding `{{ page }}` block you want to retain. If `keep_heading=True`, provide ONLY the body (no heading line, no page block) — the existing heading and page block are preserved.
levelinteger
default 2
Heading level to match (default 2 = `## `).
include_preceding_page_breakboolean
default true
If True (default), an immediately preceding `{{ page }}` block is part of the slice. Ignored when keep_heading=True.
keep_headingboolean
default false
If True, keep the existing heading line + preceding page block, replace only the body that follows. Saves you from retyping the heading and prevents accidental heading-level mistakes.

Grids

grids_cloneClone grid

writeGrids

Clone an existing grid into a new one, with optional overrides for layout, mapping, and config.

Description and parameters (16)
Clone an existing grid into a new one, with optional overrides for layout, mapping, and config.
ParameterTypeDescription
source_gridrequiredstring
new_grid_namerequiredstring
layoutstring | null
mappingstring | null
header_titlestring | null
footer_footnotestring | null
footer_pagenumboolean | null
border_stylestring | null
border_colorstring | null
border_cornerstring | null
border_labelstring | null
themestring | null
color_themestring | null
display_namestring | null
descriptionstring | null
summarystring | null

grids_createCreate grid

writeGrids

Create a Novem grid dashboard with layout, mapping, and optional configuration.

Description and parameters (19)
Create a Novem grid dashboard with layout, mapping, and optional configuration.

    CRITICAL - Layout and Mapping Syntax:

    Layout must be ASCII box art with {ID:-} placeholders:
    Example (RECOMMENDED FORMAT with vertical spacing):
        layout = "+---------------------------+---------------------------+
|                           |                           |
|          {A:-}            |          {B:-}            |
|                           |                           |
+---------------------------+---------------------------+
|                           |                           |
|          {C:-}            |          {D:-}            |
|                           |                           |
+---------------------------+---------------------------+"

    IMPORTANT Layout Rules:
    - Use +, -, | for box drawing
    - Placeholders: {ID:-} where ID is a single letter/number
    - Cell width (dashes) determines horizontal space - use at least 25-30 dashes per cell
    - CRITICAL: Include empty lines above/below placeholders for vertical spacing
    - Custom plots and complex visualizations REQUIRE adequate spacing to render
    - Without vertical spacing, plots may fail to render completely

    Mapping binds each placeholder to a plot with format: "ID => REFERENCE,options"
    Example:
        mapping = "A => /p/sales-summary,c=t
B => u/acme/p/revenue-trend,c=t,m=d,s=2
C => https://novem.io/u/acme/p/regional-comparison,c=t,tbg=f"

    - References accept a shortname; /p/name or p/name; /u/user/p/name or
      u/user/p/name; and official https://novem.io/u/user/p/name URLs
    - Comma options (preferred): c=t/f (caption), h=t/f (header),
      m=l/d (mode), s=1/2/3 (scale), tbg=t/f (transparent background)
    - Standard query options also work, e.g. /p/plot-name?c=t&m=d&scale=2

    Args:
        grid_name: Grid identifier
        layout: ASCII box art layout with {ID:-} placeholders
        mapping: Panel-to-plot mapping (format: "ID => /p/plot-name,c=t")
        header_title: Header title text (optional)
        footer_footnote: Footer footnote text (optional)
        footer_pagenum: Show page numbers (optional)
        border_style: Border style - "single", "double", "none" (optional)
        border_color: Border color hex code, e.g., "#2c3e50" (optional)
        border_corner: Border corners - "round", "square" (optional)
        border_label: Border label text (optional)
        theme: Theme name (optional)
        color_theme: Color theme (optional)
        display_name: Display name in web app (optional)
        description: Grid description (optional)
        summary: Grid summary (optional)
        grid_type: Grid type setting (default: "fs" for fullscreen layout, better for most cases)
                  Other options: "default" for standard layout
        include_preview: If True, embed preview reference (optional)
        include_layout: If True, embed layout in response (optional)
        include_mapping: If True, embed mapping in response (optional)

    Returns:
        CallToolResult with grid URL and configuration status
ParameterTypeDescription
grid_namerequiredstring
layoutrequiredstring
mappingrequiredstring
header_titlestring | null
footer_footnotestring | null
footer_pagenumboolean | null
border_stylestring | null
border_colorstring | null
border_cornerstring | null
border_labelstring | null
themestring | null
color_themestring | null
display_namestring | null
descriptionstring | null
summarystring | null
grid_typestring
default "fs"
include_previewboolean
default false
include_layoutboolean
default false
include_mappingboolean
default false

grids_get_configGet grid config

read-onlyGrids

Retrieve the JSON config/metadata for a grid.

Description and parameters (1)
Retrieve the JSON config/metadata for a grid.
ParameterTypeDescription
grid_namerequiredstring

grids_get_previewPreview grid

read-onlyGrids

Get a rendered output file for a grid.

Description and parameters (2)
Get a rendered output file for a grid.

Returns an embedded resource URI — call resources/read with that URI to
get the binary.

Note: ASCII (`txt`) preview is not supported for grids. Grids are
typically composed of custom plots, and the server-side renderer can't
represent custom JS visualisations as text.
ParameterTypeDescription
grid_namerequiredstringName of the grid.
formatstring
default "png"
Output format — 'png' (default) or 'pdf'.

grids_updateUpdate grid

destructiveGrids

Update grid layout/mapping/config without recreating. Only supplied fields are updated.

Description and parameters (17)
Update grid layout/mapping/config without recreating.
    Only supplied fields are updated.

    IMPORTANT - Layout Format (if updating layout):
    - Include empty lines above/below placeholders for vertical spacing
    - Use at least 25-30 dashes per cell for horizontal space
    - Example working format:
        "+---------------------------+---------------------------+
|                           |                           |
|          {A:-}            |          {B:-}            |
|                           |                           |
+---------------------------+---------------------------+"
    - Without proper spacing, custom plots may fail to render

    Parameters:
        layout: ASCII box art layout with {ID:-} placeholders (see format above)
        mapping: Panel-to-plot mapping (format: "ID => /p/plot-name,c=t")
        grid_type: Grid type setting (e.g., "fs" for fullscreen, "default" for standard)
        header_title, footer_footnote, border_style, theme, etc.: Optional configuration
        match_grid: Optional grid name to copy layout/mapping/styling from. If provided,
                   copies layout, mapping, and all configuration from the source grid.
                   Explicit parameters override the copied values.

    Examples:
        # Copy layout and styling from another grid
        update_grid(
            grid_name="new-dashboard",
            match_grid="crypto-spaced-2x2"
        )

        # Match a grid but override specific settings
        update_grid(
            grid_name="new-dashboard",
            match_grid="crypto-spaced-2x2",
            header_title="Custom Title"
        )
ParameterTypeDescription
grid_namerequiredstring
layoutstring | null
mappingstring | null
header_titlestring | null
footer_footnotestring | null
footer_pagenumboolean | null
border_stylestring | null
border_colorstring | null
border_cornerstring | null
border_labelstring | null
themestring | null
color_themestring | null
display_namestring | null
descriptionstring | null
summarystring | null
grid_typestring | null
match_gridstring | null

Mails

mails_cloneClone mail

writeMails

Clone an existing mail into a new mail, with optional overrides (subject, content, recipients, theme, etc.).

Description and parameters (12)
Clone an existing mail into a new mail, with optional overrides (subject, content, recipients, theme, etc.).
ParameterTypeDescription
source_mailrequiredstring
new_mail_namerequiredstring
subjectstring | null
contentstring | null
to_recipientsstring | null
cc_recipientsstring | null
bcc_recipientsstring | null
reply_tostring | null
sizestring | null
themestring | null
descriptionstring | null
summarystring | null

mails_createCreate mail

writeMails

Create a new mail resource with content and optional recipients/config.

Description and parameters (12)
Create a new mail resource with content and optional recipients/config.
ParameterTypeDescription
mail_namerequiredstringUnique mail identifier (no spaces)
subjectrequiredstringMail subject line
contentrequiredstringMarkdown body (supports Novem template syntax). For example: # Example weekly summary
display_namestring | nullWebapp display name for the mail (POST /name).
to_recipientsstring | nullOptional newline-separated primary recipients
cc_recipientsstring | nullOptional newline-separated CC recipients
bcc_recipientsstring | nullOptional newline-separated BCC recipients
reply_tostring | nullReply-to email or "yes"/"noreply" value
sizestring | nullOptional size (e.g., "small")
themestring | nullOptional theme
descriptionstring | nullOptional description
summarystring | nullOptional summary

mails_get_configGet mail config

read-onlyMails

Retrieve the configuration and metadata for a mail.

Description and parameters (1)
Retrieve the configuration and metadata for a mail.
ParameterTypeDescription
mail_namerequiredstring

mails_get_previewPreview mail

read-onlyMails

Get a rendered output file for a mail.

Description and parameters (2)
Get a rendered output file for a mail.

Use this to retrieve a mail as PNG, PDF, or plain text.
For png and pdf, returns a resource URI — call resources/read with that URI to get the binary.
For txt, returns the text content directly.
ParameterTypeDescription
mail_namerequiredstringName of the mail.
formatstring
default "png"
Output format — "png" for image, "pdf" for PDF document, "txt" for text export.

mails_sendSend mail

destructiveMails

Trigger sending of a prepared mail.

Description and parameters (3)
Trigger sending of a prepared mail.

By default the mail goes to its stored recipients (POST /status with
'send'). Pass `to` to send this one delivery to ad-hoc addresses instead:
the supplied addresses replace the stored recipient list for this send
only. Ad-hoc sends take direct e-mail addresses only — not cc/bcc, @user
handles or groups — and the mail's content, subject and theme are
unchanged. Sending to direct addresses requires a paid plan.
ParameterTypeDescription
mail_namerequiredstringThe mail to send.
toarray of string | nullOptional ad-hoc recipient addresses. When supplied, replaces the stored recipient list for this send only.
notestring | nullOptional note surfaced in the confirmation prompt.

mails_updateUpdate mail

destructiveMails

Update mail configuration/content/recipients without recreating. Only supplied fields are updated.

Description and parameters (12)
Update mail configuration/content/recipients without recreating.
Only supplied fields are updated.
ParameterTypeDescription
mail_namerequiredstring
subjectstring | null
contentstring | null
display_namestring | null
to_recipientsstring | null
cc_recipientsstring | null
bcc_recipientsstring | null
reply_tostring | null
sizestring | null
themestring | null
descriptionstring | null
summarystring | null

Jobs

jobs_createCreate job

writeJobs & Repos

Create a new job in Novem that runs a chain step from a git repository.

Description and parameters (7)
Create a new job in Novem that runs a chain step from a git repository.

Jobs are automated tasks that run in isolated Docker containers. They can:
- Process uploaded files (CSV, JSON, TXT)
- Update Novem visualizations
- Fetch data from external APIs
- Run on schedules (cron syntax)
- Execute on-demand via jobs_run_now() or jobs_run_with_file()

The job's /config/chains is set to the short-form repo ref (resolves to
@<owner>/<repo_name>:latest), giving a single-step chain. The image is
produced by the repo's push build — push code via git before running.
For multi-step DAGs (multiple repos piped together) write /config/chains
directly via general_api_POST; see general_help(topic='jobs').

Jobs run in Docker containers with:
- /input/ directory: Files and JSON payloads
- /output/ directory: Results written here
- Environment variables: Credentials and configuration

Returns:
    CallToolResult with job configuration and URL

Prerequisites:
    1. Repository must exist (create with repos_create())
    2. Code must be pushed to repository via git — the push builds the
       chain-runnable image at @<owner>/<repo_name>:latest
    3. Repository should contain a main Python script (or a Dockerfile)
    4. Script must handle /input and /output directories

Job Script Requirements:
    - Read /input and write /output directly; the image receives no extra arguments
    - List files in /input before processing
    - Write results to /output/result.txt
    - Access env vars via os.environ

Examples:
    # Job that updates Novem plot via API (needs token)
    jobs_create(
        job_name="plot-updater",
        job_description="Fetch data and update plot via API",
        repo_name="plot-jobs",
        env_vars={
            "PLOT_NAME": "sales_dashboard"
        },
        auto_create_token=True  # Declares API access; token injected per run
    )

    # Job that only processes files (no token needed)
    jobs_create(
        job_name="csv-processor",
        job_description="Process uploaded CSV and output summary",
        repo_name="data-jobs",
        auto_create_token=False  # No API requests, no token needed
    )

    # Scheduled job with API access
    jobs_create(
        job_name="daily-sync",
        job_description="Sync external data to Novem plots",
        repo_name="sync-jobs",
        schedule="0 8 * * *",  # Daily at 8 AM
        auto_create_token=True  # Needs API access to update plots
    )

Best Practices:
    1. Test before scheduling: Use jobs_run_now() to verify execution
    2. Store secrets in env_vars, never hardcode in code
    3. Use descriptive names: "daily-sales-report" not "job1"
    4. Check logs after creation: jobs_get_log(job_name) or jobs_get_log(job_name, run_name=...)
    5. Start without schedule, add later: jobs_update(job_name, schedule="...")

Security Notes:
    - Tokens only needed for jobs making API requests to Novem
      (updating plots, sending mails, etc.)
    - Jobs that only process files don't need tokens
    - Use auto_create_token=True for jobs that need API access
    - Auto-created tokens are never exposed in chat or stored in memory
    - Each job gets its own token, isolated from your main account
    - Environment variables are stored securely on the backend
    - Keys are normalized to lowercase
    - Use Content-Type: text/plain for CSV data POSTs to plots

Common Mistakes:
    Creating job before pushing code to repository
    Hardcoding credentials in job script
    Using uppercase in job_name
    Scheduling without testing first

Data Integrity:
    Jobs that fetch or process data must use REAL data sources. Never generate
    synthetic or placeholder data without explicitly informing the user that
    the data is artificial.

See also:
    - repos_create(): Create repository for job code
    - jobs_run_with_file(): Execute with file upload
    - jobs_run_now(): Trigger with JSON payload
    - jobs_update(): Modify configuration
    - jobs_set_env(): Update environment variables
    - general_help(topic='ecosystem'): Python library and CLI usage
    - general_help(topic='api-structure'): REST API patterns
    - general_help(topic='jobs'): Comprehensive jobs documentation
    - general_help(topic='jobs-examples'): Working code examples
ParameterTypeDescription
job_namerequiredstringUnique identifier (lowercase, alphanumeric, hyphens only) Example: "daily-sales-report"
job_descriptionrequiredstringHuman-readable description of what the job does Example: "Process sales data and update dashboard"
repo_namerequiredstringName of git repository containing job code (must exist) Created via repos_create() tool. The repo's push build produces the image this job's chain step runs.
schedulestring | nullOptional cron expression for automatic execution Examples: - "0 8 * * *" = Daily at 8 AM - "0 */4 * * *" = Every 4 hours - "0 0 * * 0" = Weekly on Sunday at midnight Use https://crontab.guru/ to validate syntax
env_varsobject | nullOptional environment variables as key/value pairs. Use for configuration parameters and custom settings. Keys are normalized to lowercase.
auto_create_tokenboolean
default false
If True, names the claim the job runs with (access_claim, default global: the job acts as its owner). A job that already names a claim keeps it unchanged. The platform then provisions NOVEM_TOKEN itself for every run: minted at launch for the job's owner, injected into the job's environment, revoked when the run ends. Only the job's owner can grant this; a scoped or non-owner session is told so in the result, and a job whose other writers hold write shares, or whose config/env still holds a hand-pasted NOVEM_TOKEN, is told what to change first. Only needed for jobs that make API requests to Novem (e.g., updating plots, sending mails). Jobs that only process files don't need it. No token is ever exposed in chat or stored anywhere. Default: False
access_claimstring | nullWhich claim the job runs with when granting access: "global" (everything the owner can do — the default), "repo_ro" (clone the owner's repos, nothing else) or "repo_rw" (clone and push). Pick the narrowest that covers the job's API calls. Setting this implies auto_create_token=True.

jobs_delete_envDelete job environment variables

destructiveJobs & Repos

Delete one or more environment variable keys from a job.

Description and parameters (2)
Delete one or more environment variable keys from a job.

job_name is your job's name, or a job shared with you for write as
'@<owner>~<job>' or '/u/<owner>/j/<job>'.
ParameterTypeDescription
job_namerequiredstring
keysrequiredarray of string

jobs_get_configGet job config

read-onlyJobs & Repos

Retrieve job config (repo, schedule, env names).

Description and parameters (1)
Retrieve job config (repo, schedule, env names).

job_name is your job's name, or a job shared with you as '@<owner>~<job>'
or '/u/<owner>/j/<job>'.
ParameterTypeDescription
job_namerequiredstring

jobs_get_logGet job log

read-onlyJobs & Repos

Get logs and run history for a specific job in Novem.

Description and parameters (2)
Get logs and run history for a specific job in Novem.
ParameterTypeDescription
job_namerequiredstringName of your job, or a job shared with you as '@<owner>~<job>' or '/u/<owner>/j/<job>'
run_namestring | nullOptional run name. If omitted, fetches the latest run's log.

jobs_list_envList job environment

read-onlyJobs & Repos

List environment variable names for a job. Values are never returned.

Description and parameters (1)
List environment variable names for a job. Values are never returned.

job_name is your job's name, or a job shared with you as '@<owner>~<job>'
or '/u/<owner>/j/<job>'; a read share lists names only.

Keys are returned lowercased as stored, but each is exposed inside the
running container in both lowercase and uppercase forms.
ParameterTypeDescription
job_namerequiredstring

jobs_run_nowRun job now

destructiveJobs & Repos

Trigger a job to run immediately with an optional JSON payload.

Description and parameters (2)
Trigger a job to run immediately with an optional JSON payload.

This tool sends a JSON payload to the job, which creates /input/input.json
in the job's container. Use this for passing configuration parameters or
triggering jobs without file uploads.

**IMPORTANT:** For file uploads, use jobs_run_with_file() instead. This tool
only supports JSON payloads and will not properly handle file uploads.

Returns:
    CallToolResult with trigger confirmation and job status

Example:
    # Trigger job with configuration
    jobs_run_now(
        job_name="plot-updater",
        payload={"plot_name": "sales", "date_range": "last_7_days"}
    )

    # Check execution results (fetches latest run's log)
    logs = jobs_get_log("plot-updater")
    # Or fetch a specific run's log
    logs = jobs_get_log("plot-updater", run_name="run-id")

Note:
    - Job receives payload in /input/input.json
    - Empty payload creates empty JSON object {}
    - For file processing, use jobs_run_with_file() instead
    - Check jobs_get_log() for execution details (optionally pass run_name)
    - A run that outlasts this call's timeout comes back with status
      "running" and the trigger time. It is not a failure, so do not
      trigger the job again. In jobs_get_log(), an api run started after
      that time is a candidate; with other triggers queued it may not be
      this one. A queued run can take a while to appear there.

Data Integrity:
    Jobs that fetch or process data must use REAL data sources. Never generate
    synthetic or placeholder data without explicitly informing the user.

See also:
    - general_help(topic='jobs'): Comprehensive job documentation
    - general_help(topic='jobs-examples'): Working code examples
    - general_help(topic='ecosystem'): Python library for job scripts
ParameterTypeDescription
job_namerequiredstringName of your job to execute, or a job shared with you as '@<owner>~<job>' or '/u/<owner>/j/<job>'
payloadobject | nullOptional JSON-serializable dictionary passed to the job. Creates /input/input.json with this content.

jobs_run_with_fileRun job with files

destructiveJobs & Repos

Upload one or more files (text or binary) to a job and execute it synchronously.

Description and parameters (5)
Upload one or more files (text or binary) to a job and execute it synchronously.

This tool uploads files via multipart/form-data, triggers job execution in a
Docker container, and returns the job's output directly. The workflow:

1. File(s) uploaded to job endpoint
2. Job container starts with files in /input/ directory
3. Job processes files and writes to /output/result.txt (or multiple output files)
4. HTTP response returns output (single file as text, multiple files as ZIP)

Jobs run in isolated Docker containers with:
- /input/ directory: Contains uploaded file(s)
- /output/ directory: Where job writes results
- Environment variables: Configured via jobs_set_env()

Returns:
    CallToolResult with:
    - Summary message
    - Structured data including job output from /output/result.txt
    - Input/output sizes for verification

Use Cases:
    - Process CSV data files
    - Analyze text reports
    - Update Novem plots from data
    - Generate summaries from uploaded content
    - Transform data formats

Examples:
    # Text file upload (single)
    result = jobs_run_with_file(
        job_name="sales-analyzer",
        filename="sales_2024.csv",
        file_content="Date,Amount,Region\n2024-01-01,1000,North\n2024-01-02,1500,South\n"
    )
    print(result.structuredContent["output"])  # Job's output from /output/result.txt

    # Binary file upload (PDF, image, etc.)
    import base64
    with open("report.pdf", "rb") as f:
        pdf_base64 = base64.b64encode(f.read()).decode("utf-8")

    result = jobs_run_with_file(
        job_name="pdf-analyzer",
        filename="report.pdf",
        file_content=pdf_base64,
        encoding="base64"
    )

    # Multiple files upload (all values use base64)
    result = jobs_run_with_file(
        job_name="multi-file-processor",
        files={
            "document.txt": base64.b64encode(b"Example document").decode("ascii"),
            "report.pdf": pdf_base64
        },
        encoding="base64"
    )
    # When multiple output files are created, result is a ZIP archive

Job Script Requirements:
    Your job script must:
    1. Read /input and write /output directly; no extra arguments are supplied
    2. List files in /input directory (it's a directory, not a file!)
    3. Process the uploaded file(s)
    4. Write results to /output/result.txt

    Example job script:
    ```python
    import os

    input_dir = "/input"
    output_dir = "/output"

    # List and process files
    files = os.listdir(input_dir)
    file_path = os.path.join(input_dir, files[0])

    with open(file_path, 'r') as f:
        data = f.read()
        # ... process data ...

    # Write results
    result_file = os.path.join(output_dir, 'result.txt')
    with open(result_file, 'w') as out:
        out.write(f"Processed {len(data)} bytes\n")
    ```

Notes:
    - **Synchronous execution**: Response waits for job completion
    - **Long runs**: A run that outlasts this call's timeout comes back with
      status "running", the trigger time and no output. Do not run the
      job again. In jobs_get_log(), an api run started after that time is
      a candidate; with other triggers queued it may not be this one. A
      queued run can take a while to appear there.
    - **File types supported**: Text (CSV, JSON, TXT) and binary (PDF, PNG, JPG, etc.)
      For binary files, encode to base64 and set encoding="base64"
    - **File placement**: Uploaded file(s) appear in /input/ directory
    - **Output format**: Single output file returns as text, multiple outputs as ZIP
    - **Multiple files**: Job receives all files in /input/ directory
    - **Error handling**: Job failures return in error field of result
    - **Base64 encoding**: For binary files, use base64.b64encode(bytes).decode("utf-8")
      The tool automatically decodes base64 before uploading to the job

Common Mistakes:
    Expecting input and output paths on the command line
    Not listing files in /input before processing
    Writing to wrong output location
    Using jobs_run_now() for file uploads (use this tool instead!)

See also:
    - jobs_run_now(): For JSON payloads without files
    - jobs_create(): Set up jobs with repositories
    - jobs_get_log(): View execution history and debug issues (optional run_name)
    - general_help(topic='jobs'): Comprehensive job documentation
    - general_help(topic='jobs-examples'): Working code examples
    - general_help(topic='ecosystem'): Python library for job scripts
ParameterTypeDescription
job_namerequiredstringName of the job to execute (must already exist), or a job shared with you as '@<owner>~<job>' or '/u/<owner>/j/<job>'
filenamestringName for single uploaded file (e.g., "data.csv", "report.pdf") Optional - use this OR files parameter, not both
file_contentstringContent of single file as a string. For text files: plain text content For binary files: base64-encoded string (set encoding="base64") Optional - use this OR files parameter, not both
filesobjectDictionary mapping filenames to their contents (for multiple files) For text files: {"file1.csv": "plain text"} For binary files: {"file1.pdf": "base64encodedstring"} Optional - use this OR filename/file_content, not both
encodingstring
default "text"
Encoding type for file content (default: "text") - "text": Content is plain text (for CSV, JSON, TXT, etc.) - "base64": Content is base64-encoded binary (for PDF, PNG, JPG, etc.) Applies to both single file and all files in files dict

jobs_set_envSet job environment variables

destructiveJobs & Repos

Set or update environment variables for an existing job.

Description and parameters (4)
Set or update environment variables for an existing job.

**Note**: API_BASE is automatically injected with the correct API endpoint
on your own jobs. You don't need to manually set it.

**Casing**: Variable names are stored lowercased, but each variable is
exposed inside the running container under BOTH its lowercase and uppercase
forms. Setting `PLOT_NAME` makes both `plot_name` and `PLOT_NAME` available
in the job's environment, so code reading either case works.

Auto-injected variables (you don't need to set these):
    - API_BASE: Set to correct API endpoint (automatically determined from environment)
    - NOVEM_TOKEN: at run time, when the job names a claim (credential_status
      in the result says whether it does)

Examples:
    # Grant an existing job API access (API_BASE auto-injected)
    jobs_set_env(
        job_name="plot-updater",
        auto_create_token=True
    )

    # Update env vars (API_BASE auto-injected)
    jobs_set_env(
        job_name="plot-updater",
        env_vars={"PLOT_NAME": "new_plot"}
    )
ParameterTypeDescription
job_namerequiredstringName of your job to update, or a job shared with you for write as '@<owner>~<job>' or '/u/<owner>/j/<job>'
env_varsobject | nullOptional dictionary of environment variables to set/update
auto_create_tokenboolean
default false
If True, names the claim the job runs with (access_claim, default global: the job acts as its owner); the platform then provisions NOVEM_TOKEN per run — minted at launch for the owner, injected, revoked when the run ends. Only the owner can grant it; the result's credential_status / credential_note say what happened: declared, kept (already named), owner_grant_required (scoped or non-owner session), blocked (others hold write shares), legacy_token (config/env still holds a hand-pasted NOVEM_TOKEN, which keeps winning — delete it first), skipped (you supplied NOVEM_TOKEN yourself), or failed (the result is then an error). Only needed for jobs making API requests to Novem. No token is exposed in chat or stored anywhere. Default: False
access_claimstring | null"global" (default), "repo_ro" or "repo_rw" — the narrowest claim that covers the job's API calls. Setting it implies auto_create_token=True.

jobs_updateUpdate job

destructiveJobs & Repos

Update job config without recreating it. Supply only fields you want to change.

Description and parameters (5)
Update job config without recreating it. Supply only fields you want to change.

job_name is your job's name, or a job shared with you for write as
'@<owner>~<job>' or '/u/<owner>/j/<job>'.

Examples (env_vars):
  { "PLOT_NAME": "my_plot", "API_BASE": "{auto-injected}" }
ParameterTypeDescription
job_namerequiredstring
job_descriptionstring | null
repo_namestring | null
schedulestring | null
env_varsobject | null

Repos

repos_createCreate repo

writeJobs & Repos

Set up a git repository in Novem.

Description and parameters (2)
Set up a git repository in Novem.

Repositories store code for jobs that automate data processing and visualization updates.
After creating a repo, push your code via git, then create a job that references it.

The response includes the SSH remote URL. In a shell that has both NOVEM_GIT_ORIGIN and
a Novem token ($NOVEM_TOKEN, or a `token = ` line in ~/.config/novem/novem.conf), push
over HTTPS to $NOVEM_GIT_ORIGIN/u/<owner>/r/<repo>.git instead; no SSH key is needed
there. Without the token, use the SSH remote.
If a terminal is available, use standard git commands from that point on — clone,
commit, push, diff, log. The browse tools in this module (repos_diff, repos_read_file,
etc.) exist for contexts without a terminal, such as the claude.ai web interface.

Repository code typically uses:
- Novem Python library (pip install novem)
- Direct REST API calls
- Standard Python libraries for data processing

See also:
    - general_help(topic='ecosystem'): Python library installation and usage
    - general_help(topic='api-structure'): REST API patterns for job scripts
    - general_help(topic='jobs'): Creating jobs that use repo code
    - general_help(topic='jobs-examples'): Working examples
ParameterTypeDescription
repo_namerequiredstring
repo_descriptionrequiredstring

repos_diffDiff repo refs

read-onlyJobs & Repos

Show what changed between two refs (branches or commit SHAs).

Description and parameters (6)
Show what changed between two refs (branches or commit SHAs).

The public reference for the API this tool calls is https://novem.io/docs/reference/repos/api.

Two modes — pick based on what the user needs:

**Summary mode** (no path): lists every file that was added, modified, or
deleted. Compact output — one line per file. Use this first to understand
the scope of changes before drilling into a specific file.

**File diff mode** (path provided): shows a unified diff for one file,
equivalent to `git diff <from> <to> -- <path>`. Paginated: use offset and
limit to page through large diffs. Check has_more in the response to know
if more lines are available.
ParameterTypeDescription
repo_namerequiredstringName of the repository
from_refrequiredstringStarting ref — branch name or full 40-char commit SHA
to_refrequiredstringEnding ref — branch name or full 40-char commit SHA
pathstring | nullFile path to diff (omit for changed-files summary)
offsetinteger
default 0
Line offset for pagination in file diff mode (default: 0)
limitinteger
default 200
Max diff lines to return in file diff mode (default: 200)

repos_get_configGet repo config

read-onlyJobs & Repos

Retrieve repository configuration (name, description, SSH URL).

Description and parameters (1)
Retrieve repository configuration (name, description, SSH URL).
ParameterTypeDescription
repo_namerequiredstring

repos_get_logGet repo activity log

read-onlyJobs & Repos

Get the activity log for a repository.

Description and parameters (1)
Get the activity log for a repository.

Shows repository and build events: creation, pushes, the selected build
heuristic, build progress, failure tails, and per-ref failure summaries.
Use jobs_get_log for execution logs from runs of a job, not repo builds.
ParameterTypeDescription
repo_namerequiredstring

repos_list_branchesList repo branches

read-onlyJobs & Repos

List all branches in a repository with their HEAD commit SHA.

Description and parameters (1)
List all branches in a repository with their HEAD commit SHA.
ParameterTypeDescription
repo_namerequiredstring

repos_list_commitsList repo commits

read-onlyJobs & Repos

List recent commits in a repository.

Description and parameters (2)
List recent commits in a repository.
ParameterTypeDescription
repo_namerequiredstringName of the repository
limitinteger
default 20
Maximum number of commits to return (default 20, max 100)

repos_list_filesList repo files

read-onlyJobs & Repos

List files and directories in a repository at a given path and branch.

Description and parameters (3)
List files and directories in a repository at a given path and branch.

The public reference for the API this tool calls is https://novem.io/docs/reference/repos/api.
ParameterTypeDescription
repo_namerequiredstringName of the repository
pathstring
default ""
Directory path relative to repo root (default: root)
branchstring
default "main"
Branch name (default: main)

repos_read_fileRead repo file

read-onlyJobs & Repos

Read the content of a file in a repository.

Description and parameters (5)
Read the content of a file in a repository.

The public reference for the API this tool calls is https://novem.io/docs/reference/repos/api.

Paginated by line: use offset and limit to page through large files.
Check has_more in the response to know if more lines are available.
The response always includes total_lines so you can plan follow-up reads.
ParameterTypeDescription
repo_namerequiredstringName of the repository
pathrequiredstringFile path relative to repo root (e.g. 'main.py' or 'src/utils.py')
branchstring
default "main"
Branch name (default: main)
offsetinteger
default 0
Line offset for pagination (default: 0)
limitinteger
default 200
Max lines to return (default: 200)

repos_ssh_keys_addAdd SSH key

writeJobs & Repos

Register an SSH public key with Novem for git push access.

Description and parameters (5)
Register an SSH public key with Novem for git push access.

Where there is a terminal, first run `ssh git@<host from the repo URL> keys`.
It lists keys and marks the one used; confirm it belongs to the intended account.
Host-key verification or connection failures leave this check inconclusive;
resolve them and retry.

If authentication is unconfirmed, call repos_ssh_keys_list to inspect the
account's key names. The list cannot establish whether a matching private key
is available here. Without a terminal, use the repository browse tools and
only ask about local setup if a git operation is needed.

Before requesting a keypair, inspect existing local SSH keys, SSH configuration
and the SSH agent where available. "Permission denied (publickey)" can mean an
existing key needs selecting or loading; retry with that identity first.
If a suitable existing key is not registered, register its public half here.
Each machine needs access to the private half of a registered key; registering
a separate key for another machine is normal.

Generate a new keypair locally only if no suitable key exists:
    ssh-keygen -t ed25519 -C "your@email.com"
Then paste the contents of the .pub file as public_key.
ParameterTypeDescription
key_namerequiredstringShort identifier for the key (e.g. "laptop", "work-mac")
public_keyrequiredstringSSH public key content (the full line from your .pub file)
namerequiredstringDisplay name for the key
descriptionrequiredstringWhat this key is used for
summaryrequiredstringShort one-line summary

repos_ssh_keys_listList SSH keys

read-onlyJobs & Repos

List all SSH keys registered on this Novem account.

Description and parameters (0)
List all SSH keys registered on this Novem account.

Returns key names, descriptions, summaries and logs.
Key content is never returned — it stays on your local machine.

No parameters.

repos_updateUpdate repo

destructiveJobs & Repos

Update repository metadata (description/name) without recreating.

Description and parameters (3)
Update repository metadata (description/name) without recreating.
ParameterTypeDescription
repo_namerequiredstring
repo_descriptionstring | null
display_namestring | null

Spaces

spaces_copyCopy space file

destructiveSpaces

Copy (or move) a single file across spaces, or copy within one space.

Description and parameters (5)
Copy (or move) a single file across spaces, or copy within one space.

The spaces API has no copy primitive and cannot move content across
spaces, so this is a client-side workaround: it reads the source file
and writes it to the destination (and, when move=True, deletes the
source only after the copy succeeds). Because the bytes pass through
this tool it is limited to a single text file up to 256 KB — text covers
CSV/TSV/TXT/Markdown/HTML as well as JSON, XML and YAML. For binary or
larger files, use authenticated HTTP requests: download with
`curl --output`, then upload with `curl --data-binary @file`. See
`general_help(topic='spaces')` for examples. Copy folders one file at a time.

For move/rename WITHIN one space, prefer spaces_move — it is a
metadata-only operation with no size limit.
ParameterTypeDescription
src_spacerequiredstringSource space identifier.
src_pathrequiredstringSource file path.
dest_spacerequiredstringDestination space identifier.
dest_pathrequiredstringDestination file path (parent folders auto-created).
moveboolean
default false
Delete the source after a successful copy (default False).

spaces_createCreate space

writeSpaces

Create a new space (a file store).

Description and parameters (3)
Create a new space (a file store).
ParameterTypeDescription
spacerequiredstringThe space identifier — lowercase letters, digits, '_' or '-'.
display_namestring | nullOptional human-friendly name shown in the web app.
descriptionstring | nullOptional description.

spaces_create_folderCreate space folder

writeSpaces

Create a folder in a space.

Description and parameters (2)
Create a folder in a space.

The public reference for the API this tool calls is https://novem.io/docs/reference/spaces/api.

The path may be nested ('reports/2024/q4') — any missing parent
folders are created in the same call. Creating a folder inside an
existing folder works identically: just give the full path. The call
is idempotent — creating a folder that already exists succeeds.
ParameterTypeDescription
spacerequiredstringThe space identifier.
pathrequiredstringFolder path within the space, e.g. 'reports/2024/q4'.

spaces_deleteDelete space

destructiveSpaces

Delete an entire space and all of its contents.

Description and parameters (1)
Delete an entire space and all of its contents.
ParameterTypeDescription
spacerequiredstringThe space identifier to delete.

spaces_delete_fileDelete space file or folder

destructiveSpaces

Delete a file or folder within a space.

Description and parameters (3)
Delete a file or folder within a space.

The public reference for the API this tool calls is https://novem.io/docs/reference/spaces/api.

Deleting a non-empty folder requires recursive=True. Deleting space
content is a write-tier operation (write access implies delete inside
a space) — distinct from spaces_delete, which removes the whole space
and requires the delete scope.
ParameterTypeDescription
spacerequiredstringThe space identifier.
pathrequiredstringPath of the file or folder to delete.
recursiveboolean
default false
Delete a folder and everything under it (default False).

spaces_get_configGet space config

read-onlySpaces

Read a space's metadata (name, description, shortname, url).

Description and parameters (1)
Read a space's metadata (name, description, shortname, url).
ParameterTypeDescription
spacerequiredstringThe space identifier (see spaces_list).

spaces_listList spaces

read-onlySpaces

List all spaces you own or can access.

Description and parameters (0)
List all spaces you own or can access.

Returns each space's name and metadata. Use this to discover the
`space` identifier the other spaces_* tools take.

No parameters.

spaces_list_filesList space files

read-onlySpaces

List files and folders in a space, at the content root or under a folder.

Description and parameters (2)
List files and folders in a space, at the content root or under a folder.

The public reference for the API this tool calls is https://novem.io/docs/reference/spaces/api.
ParameterTypeDescription
spacerequiredstringThe space identifier.
pathstring | nullOptional folder path within the space (e.g. 'reports/2024'). Omit to list the content root.

spaces_moveMove space file or folder

destructiveSpaces

Move or rename a file or folder within a space.

Description and parameters (3)
Move or rename a file or folder within a space.

The public reference for the API this tool calls is https://novem.io/docs/reference/spaces/api.

`destination` is the new space-relative path. To rename in place, keep
the same parent folder and change the leaf (e.g. path='a/old.csv',
destination='a/new.csv'). To move, give a different folder. An
existing destination file is overwritten.
ParameterTypeDescription
spacerequiredstringThe space identifier.
pathrequiredstringCurrent path of the file or folder.
destinationrequiredstringNew space-relative path.

spaces_read_fileRead space file

read-onlySpaces

Read the contents of a file in a space.

Description and parameters (2)
Read the contents of a file in a space.

The public reference for the API this tool calls is https://novem.io/docs/reference/spaces/api.

Return text content inline. For binary files, use an authenticated
`curl --output` download to save the original bytes. See
`general_help(topic='spaces')` for an example.
ParameterTypeDescription
spacerequiredstringThe space identifier.
pathrequiredstringFile path within the space (e.g. 'data/sales.csv').

spaces_renameRename space identifier

destructiveSpaces

Rename a space's identifier (e.g. 'my_space' -> 'old_space').

Description and parameters (2)
Rename a space's identifier (e.g. 'my_space' -> 'old_space').

This changes the space's path identifier while keeping all of its
contents, folder structure, and shortname/URL intact — it is a
metadata-only rename, not a rebuild. To change only the human-facing
display name (not the identifier), use spaces_update_config instead.
ParameterTypeDescription
spacerequiredstringThe current space identifier.
new_namerequiredstringThe new identifier — lowercase letters, digits, '_' or '-'.

spaces_update_configUpdate space config

destructiveSpaces

Update a space's display name and/or description.

Description and parameters (3)
Update a space's display name and/or description.
ParameterTypeDescription
spacerequiredstringThe space identifier.
display_namestring | nullNew display name (optional).
descriptionstring | nullNew description (optional).

spaces_write_fileWrite space file

destructiveSpaces

Write a text file to a space (create or overwrite).

Description and parameters (3)
Write a text file to a space (create or overwrite).

Any missing parent folders along `path` are created automatically.
The Content-Type is inferred from the file extension.

API upload limits apply. For local text files, use the novem CLI:
    novem --space example_data -w content/data.csv @data.csv
This tool and the CLI's `-w` option accept UTF-8 text. Upload binary
files with an authenticated `curl --data-binary @file` request; see
`general_help(topic='spaces')` for an example.
ParameterTypeDescription
spacerequiredstringThe space identifier.
pathrequiredstringFile path within the space (e.g. 'data/sales.csv'). Parent folders are created as needed.
contentrequiredstringThe text content to write.

Themes

themes_createCreate theme

writeThemes

Create an org theme. Admin role on the org is required.

Description and parameters (6)
Create an org theme. Admin role on the org is required.

Reference the new theme from any vis as `+<org>/<theme>` — e.g.
`docs_set_theme(doc_name, theme="+acme/corporate")`.

For assets (logos, fonts), call `themes_upload_asset` *after* creation
and reference them from CSS as `url("./assets/<name>")`.

Prefer setting `--novem-*` CSS custom properties on `.novem--doc--page`
(palette, typography, surfaces) for the broadest cross-vis impact —
embedded custom plots inherit those values automatically.
ParameterTypeDescription
orgrequiredstringOrganization name (the `<org>` in the `+org/theme` reference).
themerequiredstringTheme name (lowercase letters/digits/hyphens/dots, 2–50 chars).
custom_cssstring | nullInitial CSS body (≤5 MiB).
descriptionstring | nullLong-form description (≤5 KB).
summarystring | nullShort tagline.
is_publicboolean | nullDefault False (org-internal). Set True only when the theme will be rendered for an audience outside the owning org — public-shared vis or vis owned by users in other orgs. Don't reflexively make themes public during dev.

themes_deleteDelete theme

destructiveThemes

Permanently delete a theme and all its assets. Admin role on the org is required.

Description and parameters (2)
Permanently delete a theme and all its assets. Admin role on the org is required.

Any vis still referencing this theme renders unstyled (no error).
ParameterTypeDescription
orgrequiredstringOrganization name.
themerequiredstringTheme name.

themes_delete_assetDelete theme asset

destructiveThemes

Delete a single asset from a theme. Admin role on the org is required.

Description and parameters (3)
Delete a single asset from a theme. Admin role on the org is required.

Any CSS rule still referencing `./assets/<asset_name>` will fail to load
that asset — clean up the CSS before deleting.
ParameterTypeDescription
orgrequiredstringOrganization name.
themerequiredstringTheme name.
asset_namerequiredstringAsset file name to remove.

themes_get_configGet theme config

read-onlyThemes

Get the metadata snapshot for a single theme: description, summary, and `is_public` flag. `is_public` may be null when read by non-admin callers.

Description and parameters (2)
Get the metadata snapshot for a single theme: description, summary, and
`is_public` flag. `is_public` may be null when read by non-admin callers.

For the CSS body, call `themes_inspect_css`. For the asset listing, call
`themes_list_assets`.
ParameterTypeDescription
orgrequiredstringOrganization name.
themerequiredstringTheme name (e.g. `corporate`).

themes_inspect_cssInspect theme CSS

read-onlyThemes

Inspect a theme's `custom.css`. Themes can be large; default `summary` returns size + head/tail slices so you don't flood context with the full body until you need to.

Description and parameters (5)
Inspect a theme's `custom.css`. Themes can be large; default `summary`
returns size + head/tail slices so you don't flood context with the full
body until you need to.
ParameterTypeDescription
orgrequiredstringOrganization name.
themerequiredstringTheme name.
modestring
default "summary"
`summary` (default — size + head/tail) or `full` (entire CSS).
head_linesinteger
default 60
Number of leading lines for `summary` mode (default 60).
tail_linesinteger
default 40
Number of trailing lines for `summary` mode (default 40).

themes_listList themes

read-onlyThemes

List themes available in an org.

Description and parameters (1)
List themes available in an org.

Reference any of these from a vis's `/config/theme` as `+<org>/<theme>`.
ParameterTypeDescription
orgrequiredstringOrganization name (the same `<org>` you'd use in `+org/theme`).

themes_list_assetsList theme assets

read-onlyThemes

List assets (logos, fonts, images) bound to a theme.

Description and parameters (2)
List assets (logos, fonts, images) bound to a theme.

Each asset can be referenced from the theme CSS as
`url("./assets/<asset_name>")`.
ParameterTypeDescription
orgrequiredstringOrganization name.
themerequiredstringTheme name.

themes_set_metadataSet theme metadata

destructiveThemes

Update a theme's description or summary text. Admin role on the org is required.

Description and parameters (4)
Update a theme's description or summary text. Admin role on the org is required.

Pass an empty string to clear a field; omit to leave it unchanged.
ParameterTypeDescription
orgrequiredstringOrganization name.
themerequiredstringTheme name.
descriptionstring | nullLong-form description (≤5 KB). Empty string clears.
summarystring | nullShort tagline. Empty string clears.

themes_set_publicSet theme public flag

destructiveThemes

Toggle a theme's `is_public` flag. Admin role on the org is required.

Description and parameters (3)
Toggle a theme's `is_public` flag. Admin role on the org is required.

Set True only when the theme will be rendered for an audience outside
the owning org — public-shared vis or vis owned by users in other orgs.
A vis whose viewer can't read the theme renders without it (falls back
to skeleton styling). For internal-only org work, leave it False.
ParameterTypeDescription
orgrequiredstringOrganization name.
themerequiredstringTheme name.
is_publicrequiredbooleanTrue → readable by anyone; False → readable only by members of the owning org.

themes_update_cssReplace theme CSS

destructiveThemes

Replace a theme's `custom.css` body. Admin role on the org is required.

Description and parameters (3)
Replace a theme's `custom.css` body. Admin role on the org is required.

Every vis referencing the theme picks up the new CSS on next render —
no per-vis update needed.

**CLI handoff:** if the CSS is already on disk (or you've read it with the
`Read` tool), prefer **`novem -O <org> -w admin/themes/<theme>/custom.css @theme.css`**.
The CLI streams the file directly — no context burn. Use this MCP tool only
when you're producing the CSS in-conversation, or when no shell is available.
See `general_help(topic='cli-handoff')`.
ParameterTypeDescription
orgrequiredstringOrganization name.
themerequiredstringTheme name.
custom_cssrequiredstringNew CSS body (≤5 MiB).

themes_upload_assetUpload theme asset

writeThemes

Upload a binary asset (logo, font, image) to a theme. Admin role on the org is required.

Description and parameters (5)
Upload a binary asset (logo, font, image) to a theme. Admin role on the org is required.

Use this tool for content generated in the conversation or when no
shell is available. For local binary files, use an authenticated
`curl --data-binary @file` upload; see `general_help(topic='themes')`
for an example. The CLI's `-w` option accepts UTF-8 text, such as SVG,
rather than binary images or fonts.

Reference the asset from the theme CSS as `url("./assets/<asset_name>")`.
ParameterTypeDescription
orgrequiredstringOrganization name.
themerequiredstringTheme name.
asset_namerequiredstringFile name (lowercase letters/digits/hyphens, optional `.ext`, ≤64 chars). The extension determines auto-inferred content type — e.g. `logo.png`, `brand-font.woff2`.
content_base64requiredstringAsset bytes encoded as base64.
content_typestring | nullOptional override. Allowed: image/png, image/jpeg, image/gif, image/svg+xml, image/webp, font/woff, font/woff2, font/ttf, font/otf. If omitted, inferred from the file extension.

Assets

assets_deleteDelete asset

destructiveany scope

Delete an asset from a VDE.

Description and parameters (2)
Delete an asset from a VDE.

Any `{{ img ref: <asset_name> }}` block or `render.assets['<name>']`
lookup still referencing this asset will break.
ParameterTypeDescription
vderequiredstringVDE FQNP (see assets_list).
asset_namerequiredstringAsset to remove.

assets_inspectInspect asset

read-onlyany scope

Inspect a single asset's metadata (size, content type, timestamps).

Description and parameters (2)
Inspect a single asset's metadata (size, content type, timestamps).

Does NOT download the bytes — only metadata. Use the listing or the
direct URL for byte access.
ParameterTypeDescription
vderequiredstringVDE FQNP (see assets_list).
asset_namerequiredstringName of the asset on the VDE.

assets_listList assets

read-onlyany scope

List assets attached to a VDE (plot, doc, or mail).

Description and parameters (1)
List assets attached to a VDE (plot, doc, or mail).
ParameterTypeDescription
vderequiredstringVDE FQNP, e.g. `/u/alice/p/myplot`, `/u/alice/d/q4-report`, or `/u/alice/m/welcome`. The long form (`/users/alice/vis/plots/myplot`) is also accepted.

assets_uploadUpload asset

writeany scope

Upload a binary asset (image, font) to a VDE.

Description and parameters (4)
Upload a binary asset (image, font) to a VDE.

Use this tool for content generated in the conversation or when no
shell is available. For local binary files, use an authenticated
`curl --data-binary @file` upload; see `general_help(topic='assets')`
for an example. The CLI's `-w` option accepts UTF-8 text, such as SVG,
rather than binary images or fonts.

Reference the uploaded asset:
  * from a doc / mail:   `{{ img ref: <asset_name> }}`
  * from a custom plot:  `render.assets['<asset_name>']`
ParameterTypeDescription
vderequiredstringVDE FQNP (see assets_list).
asset_namerequiredstringFile name (lowercase letters/digits/hyphens, optional `.ext`, ≤64 chars). Extension determines auto-inferred type.
content_base64requiredstringAsset bytes encoded as base64.
content_typestring | nullOptional override. Allowed: image/png, image/jpeg, image/gif, image/svg+xml, image/webp, font/woff, font/woff2, font/ttf, font/otf. Inferred from extension when omitted.

Prompts

Prompts are prepared instructions a client can offer you, usually as a slash command.

jobs_debug_failed_job

Jobs & Repos

Systematic workflow to debug a failing job

Arguments: job_name (required)

jobs_setup_automated_report

Jobs & Repos

Complete workflow for setting up an automated scheduled report

Resources

Resources are read-only URIs a client can fetch. A {name} in a URI is a placeholder for the resource's name.

URITypeScopeDescription
novem://api-schema
text/plainany scopeShow valid API path patterns for general_api_GET, general_api_POST, and general_api_PUT.
novem://api-schema/{module}
text/plainany scopeShow the API path schema for a single Novem module.
custom-plots://
text/plainCustom PlotsList all available custom plot resources.
custom-plots://{plot_name}/config
text/plainCustom PlotsRead the full JSON configuration for a custom plot.
custom-plots://{plot_name}/css
text/cssCustom PlotsFetch the CSS source for a custom plot.
custom-plots://{plot_name}/data
text/csvCustom PlotsFetch the CSV data backing a custom plot.
custom-plots://{plot_name}/js
text/javascriptCustom PlotsFetch the JavaScript source for a custom plot.
custom-plots://{plot_name}/pdf
application/pdfCustom PlotsFetch the rendered PDF for a custom plot.
custom-plots://{plot_name}/png
plots://{plot_name}/png
image/pngCustom PlotsFetch the rendered PNG for a plot, including native plot types.
custom-plots://{plot_name}/share/{target}
image/pngCustom PlotsFetch a share-surface PNG render for a custom plot.
docs://
text/plainDocsList all available doc resources.
docs://{doc_name}
text/plainDocsRead the config snapshot for a specific doc.
docs://{doc_name}/content
text/markdownDocsFetch the raw Novem markdown content for a doc.
docs://{doc_name}/css
text/cssDocsFetch the per-doc custom CSS body (the file at `/config/custom/custom.css`).
docs://{doc_name}/pdf
application/pdfDocsFetch the rendered PDF for a doc.
docs://{doc_name}/pptx
application/vnd.openxmlformats-officedocument.presentationml.presentationDocsFetch the rendered PPTX export for a doc.
grids://
text/plainGridsList all available grid config resources.
grids://{grid_name}/config
text/plainGridsRead JSON configuration for a specific grid.
grids://{grid_name}/pdf
application/pdfGridsFetch the rendered PDF for a grid.
grids://{grid_name}/png
image/pngGridsFetch the rendered PNG image for a grid.
mails://
text/plainMailsList all available mail config resources.
mails://{mail_name}/config
text/plainMailsRead JSON configuration for a specific mail.
mails://{mail_name}/pdf
application/pdfMailsFetch the rendered PDF for a mail.
mails://{mail_name}/png
image/pngMailsFetch the rendered PNG image for a mail.
jobs://
text/plainJobs & ReposList all available job config resources.
jobs://{job_name}/config
text/plainJobs & ReposRead configuration for a specific job.
repos://
text/plainJobs & ReposList all available repo config resources.
repos://{repo_name}/config
text/plainJobs & ReposRead configuration for a specific repo.
spaces://
text/plainSpacesList all available spaces as resource URIs.
spaces://{space}/config
text/plainSpacesRead metadata for a specific space.
themes://{org}/{theme}/assets
text/plainThemesList the assets uploaded to a theme. Each asset can be referenced from the theme CSS as `url("./assets/<asset_name>")`.
themes://{org}/{theme}
text/plainThemesRead the metadata snapshot for a theme: description and summary. Use `themes://{org}/{theme}/css` for the CSS body and `themes://{org}/{theme}/assets` for the asset listing.
themes://{org}/{theme}/css
text/cssThemesFetch a theme's `custom.css` body as raw CSS. Use the `themes_inspect_css` tool for a head/tail summary on large stylesheets.