SAS MCP Server

Official

by sassoftware

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Apply Report Operations

apply_report_operations

Destructive

Apply an ordered batch of report changes to build or modify SAS Visual Analytics reports: add pages/objects, set parameters, and swap data sources in one validated transaction.

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.
`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 — apply the operations to a NEW report with this name, leaving the source report untouched (atomic template instantiation; pairs with ``changeData``).
`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.

Addedv1.7.0Aug 7, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already mark this as destructive/non-readonly, and the description goes well beyond them: atomic all-or-nothing application, full pre-validation before any HTTP call, ETag optimistic-concurrency with one transparent retry, auto-naming/auto-sizing, write-once placement/dataRoles, and same-batch forward-reference failure. No contradiction with annotations.

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?

The definition is long, but it is front-loaded with the core purpose and organized into labeled bullets with concrete examples. Every section earns its place given the breadth of operation types and layout rules; only minor trimming might help an agent parse it faster.

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 a complex mutation tool, it covers validation behavior, atomicity, concurrency handling, layout placement rules, header restrictions, multi-page batching, save-as behavior, and verification workflow. With an output schema present, nothing an agent needs to call this correctly is missing.

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

Parameters5/5

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

Schema coverage is 100%, yet the description still adds indispensable meaning: the list of valid operation keys, a concrete addObject example, layout/title recipes, save-as atomic template instantiation paired with changeData, conflict policy semantics, and the dry_run validation value. This greatly exceeds what the input schema alone conveys.

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?

The description opens with a precise verb and resource ('Apply an ordered batch of operations to a report') and immediately positions it as 'the authoring workhorse' for adding pages/objects, setting parameters, and swapping data sources. This clearly separates it from read-only report tools and report creation/copy siblings.

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?

It explicitly states when to use the tool ('This is how you add pages...') and routes the agent to supporting tools such as describe_report_objects and get_castable_columns. It also tells the agent to read structure via get_report_outline and verify via export_report, but it does not give explicit when-not-to-use exclusions against create_report/copy_report.

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

Deploy Server