SAS MCP Server

Official

by sassoftware

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Apply Report Operations

apply_report_operations

Destructive

Build or modify SAS Visual Analytics reports by applying an ordered, atomic batch of operations to add pages, objects, parameters, and change data sources. Validates all before writing.

Instructions

Apply an ordered batch of operations to a report — the authoring workhorse.

This is how you add pages, add objects (any of the ~60 VA visual, control, and content types), set parameters, and swap data sources. operations is the native SAS Visual Analytics operations array; the whole batch is applied atomically (all succeed or nothing changes).

Operation keys (one per array element): addData, addPage, addObject, updateObject, setParameterValue, updateData, changeData, applyDataView. Call describe_report_objects for each operation's shape (operation="addData" covers formats, aggregations, and geography via dataItems) and each object's data roles, and get_castable_columns to map columns onto those roles.

Layout & titles (see describe_report_objects → placement / layout_recipes for details):

Page title — give addPage a title (e.g. {"addPage": {"pageName": "Overview", "title": "Sales Overview"}}); it becomes a text band at the top of that page's body. Page/report headers accept ONLY control objects — never text or visuals.
Chart titles — pass {"options": {"object": {"title": "..."}}} inside the object spec at add time (all types except standardContainer, which takes no options at add time).
One-batch multi-page — create pages inline with placement {"report": {"context": "new_page", "pageName": "Trends", "pagePosition": 1}} (numeric position) and target that pageName from later operations in the same batch.
Grids/columns — relativeToObject with left/right/top/bottom (geometric) or before/after (flow order) against an EXISTING object's name; same-batch forward references fail, so chain across calls using the names each result returns. Objects are auto-named and auto-sized; placement and dataRoles are write-once (updateObject changes options only).
Read structure back anytime with get_report_outline; verify visually with export_report page-by-page (see verify_hint in the result).

The tool validates every operation against the object catalog before any HTTP call (unknown/typo'd object type, non-addable object, bad data-role names or arity, disallowed object/placement keys) and reports ALL invalid operations at once. It also handles the ETag optimistic-concurrency handshake for you, retrying once transparently on a concurrent edit.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`dry_run`	No	Validate and return the normalized payload (plus any soft warnings about missing common roles) without writing anything.
`save_as`	No	False (default) edits the report in place. True applies the operations to a NEW report instead, leaving the source untouched (atomic template instantiation; pairs with ``changeData``), named by ``result_report_name`` and/or placed by ``result_folder`` — at least one is required. This flag alone decides the mode: a ``result_report_name`` or ``result_folder`` given while it is False is refused rather than acted on, so the source can never be edited or cloned by surprise. Blank values count as not given.
`report_id`	Yes	Target report id (from ``create_report`` or ``list_reports``).
`operations`	Yes	Ordered native operations array. Example element: ``{"addObject": {"object": {"barChart": {"dataSource": "CARS", "dataRoles": {"category": "Origin", "measures": ["MSRP"]}, "options": {"object": {"title": "MSRP by Origin"}}}}, "placement": {"page": {"target": "Overview"}}}}``.
`result_folder`	No	Save-as target folder URI; omit for My Folder.
`response_format`	No	``concise`` (default) returns the created page/object/ data-source names+labels; ``detailed`` also echoes the full VA response.	concise
`result_report_name`	No	Save-as name for the new report.
`result_name_conflict`	No	Save-as name-conflict policy — ``rename`` (default), ``abort``, or ``replace``.	rename

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.18.0Sep 30, 2026

changedInput schema / properties / result_report_name / description

Previous value: -"Save-as — apply the operations to a NEW report\nwith this name, leaving the source report untouched (atomic\ntemplate instantiation; pairs with ``changeData``)."New value: +"Save-as name for the new report."

addedInput schema / properties / save_as

Added value: +{
+  "default": false,
+  "description": "False (default) edits the report in place. True applies the\noperations to a NEW report instead, leaving the source untouched\n(atomic template instantiation; pairs with ``changeData``), named\nby ``result_report_name`` and/or placed by ``result_folder`` — at\nleast one is required. This flag alone decides the mode: a\n``result_report_name`` or ``result_folder`` given while it is\nFalse is refused rather than acted on, so the source can never\nbe edited or cloned by surprise. Blank values count as not given.",
+  "type": "boolean"
+}

Addedv1.7.0Aug 7, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true): discloses that the whole batch is applied atomically ('all succeed or nothing changes'), that every operation is validated against the object catalog before any HTTP call with ALL failures reported at once, that placement/dataRoles are write-once and same-batch forward references fail, and that the ETag optimistic-concurrency handshake is retried once transparently. This is rich, non-obvious behavioral context an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose before the detailed bullet list, and the content is dense rather than repetitive — the inline examples and layout recipes carry genuine information. It is nonetheless long, and some bullets (e.g. chart-title and grid-placement detail) sit near the edge of what a tool description should carry versus delegating to describe_report_objects.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter batch-mutation tool with ~60 object types, this covers everything an agent needs: atomicity, pre-flight validation, concurrency handling, save-as mode, layout/titles, and where to verify results. An output schema exists, so return-value detail is correctly omitted.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds real meaning beyond it by explaining the operations array's element structure, the valid operation keys, placement semantics (geometric vs flow-order, same-batch reference limits), and layout/title conventions. The one gap is that save-as flags are documented only in the schema, not reinforced in the prose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Apply an ordered batch of operations to a report') and immediately characterizes scope ('the authoring workhorse'), then enumerates the concrete authoring actions (add pages, add objects, set parameters, swap data sources). This clearly separates it from siblings like get_report_outline, export_report, and create_report, so an agent can identify it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to complementary tools for sub-tasks ('Call describe_report_objects for each operation's shape', 'get_castable_columns to map columns onto those roles', read back with get_report_outline, verify with export_report). It gives clear context for when this is the right tool, but never states a when-not/exclusion case (e.g. which edits belong to other tools instead), so it stops just short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server