How do I use pbirb-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pbirb-mcp Open ~/Reports/sales.rdl and list its datasets and parameters." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

pbirb-mcp

by mafaq229

Overview Schema Source Related Servers Discussions Admin

Python

Local

pbirb-mcp

PyPI Python versions License: MIT

An MCP server for editing Power BI Report Builder paginated reports (.rdl) through Claude (Desktop, CLI, or any MCP client). 140+ tools cover the gaps that otherwise force hand-written XML: report creation, data sources and datasets, calculated fields, dataset and tablix filters, groupings (row, column, matrix), sorting, charts, headers and footers, body composition, layout containers, positioning, styling, page setup, pagination, advanced parameters, embedded images, interactivity (actions, tooltips, document map), transactions, and validation.

The server speaks JSON-RPC 2.0 over stdio. It opens an .rdl from disk, mutates it in place via lxml, validates structure, and writes atomically — a failed save never leaves a half-written report or scrubs the original.

Stability

Pre-1.0. The tool surface — tool names, inputSchema, output shapes, error semantics — is the contract. While on 0.x, MINOR releases may include a small breaking change with a migration note in CHANGELOG.md; after v1.0, breaking changes require MAJOR. See CONTRIBUTING.md for the full bump rules adapted from SemVer for an MCP tool surface.

Pin to a MINOR while on 0.x (e.g. pbirb-mcp~=0.1) if your prompts depend on specific tool names or schemas.

Related MCP server: Power BI MCP for Claude

Quick start

1. Install

The simplest path is uv + PyPI — no clone, no venv, no install step:

uvx pbirb-mcp

uvx fetches the package into a throwaway environment, runs the pbirb-mcp console script, and exits. The MCP server speaks JSON-RPC over stdio, so any MCP client (Claude Desktop, Claude Code, etc.) can spawn it directly.

For local development against this codebase instead:

git clone https://github.com/mafaq229/pbirb-mcp
cd pbirb-mcp
uv venv .venv
uv pip install --python .venv/bin/python -e ".[dev]"

Verify the binary works:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}\n' \
  | .venv/bin/pbirb-mcp

You should see a single JSON-RPC response with protocolVersion, capabilities.tools, and serverInfo.name = "pbirb-mcp".

2. Wire into Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pbirb": {
      "command": "uvx",
      "args": ["pbirb-mcp"]
    }
  }
}

Restart Claude Desktop. The hammer icon should show pbirb and the 140+ tools listed below.

To enable file logging, add an env block — but keep it platform-appropriate. PBIRB_MCP_LOG_FILE takes an OS-native path: a Unix path like /tmp/pbirb-mcp.log only works on macOS/Linux. On Windows use a Windows path (e.g. %TEMP%\\pbirb-mcp.log). See Logging. When unset, logs go to stderr, which Claude Desktop captures in its MCP debug pane on every platform.

For development against a local checkout, swap the args for ["--from", "/absolute/path/to/pbirb-mcp", "pbirb-mcp"] so uvx runs your working tree instead of the published version.

3. Wire into Claude Code

claude mcp add pbirb -- uvx pbirb-mcp

Or add to .mcp.json at the workspace root:

{
  "mcpServers": {
    "pbirb": {
      "command": "uvx",
      "args": ["pbirb-mcp"]
    }
  }
}

Or install it as a Claude Code plugin — one command instead of editing config by hand (it wires up the same uvx pbirb-mcp server for you):

/plugin marketplace add mafaq229/pbirb-mcp
/plugin install pbirb-mcp@pbirb

4. Smoke test

In any chat, ask the model:

Open ~/path/to/some-report.rdl and tell me what datasets and parameters it has.

The model should call describe_report, get_datasets, and get_parameters and summarise the result. If it doesn't, your client probably hasn't loaded the server — check the client's MCP debug log.

Working with a report

The recommended flow is read first, then edit by name. Every mutating tool addresses elements by their RDL Name attribute (Tablix name, Textbox name, ReportParameter name, DataSet name) — never by index. Indices break across multi-step edits.

A typical session:

You:    Bind the existing report at ~/Reports/sales.rdl to the Finance
        workspace's "FY26 Sales" dataset, change the body DAX to a date-
        ranged query, and add a header with a logo and a parameter line.

Claude: → describe_report(path=…)
        → set_datasource_connection(name="PBIDataset",
              workspace_url="Finance", dataset_name="FY26 Sales")
        → update_dataset_query(dataset_name="MainDataset",
              dax_body="EVALUATE FILTER('Sales',
                'Sales'[OrderDate] >= @DateFrom &&
                'Sales'[OrderDate] <= @DateTo)")
        → add_query_parameter(dataset_name="MainDataset",
              name="DateFrom",
              value_expression="=Parameters!DateFrom.Value")
        → add_query_parameter(dataset_name="MainDataset",
              name="DateTo",
              value_expression="=Parameters!DateTo.Value")
        → add_embedded_image(name="Logo",
              mime_type="image/png", image_path="~/brand/logo.png")
        → set_page_header(height="0.75in",
              print_on_first_page=True, print_on_last_page=True)
        → add_header_image(name="HeaderLogo",
              image_source="Embedded", value="Logo",
              top="0in", left="0in", width="1in", height="0.5in")
        → add_header_textbox(name="DateLine",
              text='="From: " & Parameters!DateFrom.Value & "  To: "
                    & Parameters!DateTo.Value',
              top="0.1in", left="1.2in", width="4in", height="0.25in")

Open the resulting .rdl in Report Builder; the change is visible in the designer and renders in Preview against the bound dataset.

Tool reference

143 tools, grouped by RDL concern. The highlights of each group are tabled below; the authoritative, always-current list with full schemas is the server's tools/list output, visible to the LLM at registration time. Every tool takes a path argument (absolute path to the .rdl).

Most mutating tools also accept an optional transaction_id so a multi-step edit batches into a single atomic save — see Transactions and docs/TRANSACTIONS.md.

Read-only inventory

The "what's in this report?" tools. Always the first calls when planning a multi-step edit.

Tool	Returns
`describe_report`	Top-level inventory: data sources, datasets, parameters, tablixes, page setup
`get_datasets` / `get_dataset`	Full DAX command text, fields, query parameters, dataset filters (all, or one by name)
`list_data_sources` / `get_data_source`	Data source inventory; one source's connection details
`get_parameters`	Report parameters with data type, prompt, and flags (multi-value, hidden, nullable, allow-blank)
`get_tablixes`	Tablix layout: columns, row/column groups, sort expressions, filters, visibility
`list_tablix_filters` / `list_dataset_filters`	Filters in document order with stable indices
`list_body_items` / `list_header_items` / `list_footer_items`	Named report items in each region
`get_textbox` / `get_image` / `get_rectangle` / `get_chart`	Full properties of a named report item
`list_embedded_images` / `get_embedded_image_data`	Embedded image names + MIME types; base64 bytes of one
`get_expression_reference`	Cheat-sheet of common RDL expression patterns (`count_where`, `sum_where`, `iif_format` helpers build these)

Datasource & dataset

Tool	What it edits
`set_datasource_connection`	Repoint a `<DataSource>` at a Power BI XMLA endpoint. `DataProvider=SQL` (the AS provider id).
`add_data_source` / `remove_data_source` / `rename_data_source`	Manage `<DataSource>` elements
`update_dataset_query`	Replace `<DataSet>/<Query>/<CommandText>` with a DAX expression
`add_query_parameter`	Append `<QueryParameter>` (e.g. `=Parameters!DateFrom.Value`)
`update_query_parameter`	Change the value expression of an existing query parameter
`remove_query_parameter`	Drop a query parameter (and clean up empty `<QueryParameters>`)
`add_dataset_field` / `remove_dataset_field`	Manage `<Field>` entries on a dataset
`add_calculated_field` / `remove_calculated_field`	Manage `<Value>`-backed calculated fields
`refresh_dataset_fields`	Re-derive the `<Fields>` list from the query's column metadata
`add_dataset_filter` / `remove_dataset_filter`	Filters applied at the dataset level (vs. tablix)

Tablix

Tool	What it edits
`add_tablix_filter`	Append a `<Filter>`. Operators: Equal, NotEqual, GreaterThan, In, Between, Like, TopN, ...
`remove_tablix_filter`	Remove by ordinal index from `list_tablix_filters`
`add_row_group` / `remove_row_group`	Wrap the row hierarchy in a new outer group + header row (and its inverse)
`add_column_group` / `remove_column_group`	Same, on the column axis
`convert_to_matrix`	Promote a table to a matrix (row + column groups) — see docs/MATRIX-cookbook.md
`set_tablix_corner`	Set the matrix corner cell text/expression
`set_group_sort` / `set_column_group_sort`	Replace `<SortExpressions>` on a group
`set_group_visibility` / `set_column_group_visibility`	Set `<Visibility>` on a group's TablixMember
`set_detail_row_visibility`	Set `<Visibility>` on the Details group
`add_tablix_column` / `remove_tablix_column`	Add/drop a column across the tablix grid
`add_static_row` / `add_static_column`	Insert a non-grouped row/column
`add_subtotal_row` / `add_subtotal_column`	Insert an aggregate row/column on a group
`set_cell_span`	Set `RowSpan` / `ColSpan` on a cell
`set_column_width` / `set_row_height`	Set `<Width>` / `<Height>` on the Nth column/row
`set_tablix_size`	Set the tablix's overall `<Width>` / `<Height>`

Page

Tool	What it edits
`set_page_setup`	Page dimensions, margins, columns. All fields optional.
`set_page_orientation`	Swap PageHeight/PageWidth to match `Portrait` or `Landscape`. Idempotent.

Page header & footer

Same set of operations for each region, each accepts named items so follow-up edits don't drift on indices.

Tool	What it edits
`set_page_header` / `set_page_footer`	Section height + `PrintOnFirstPage` / `PrintOnLastPage`
`add_header_textbox` / `add_footer_textbox`	Append a Textbox (static text or `=expression`)
`add_header_image` / `add_footer_image`	Append an Image (External URL, Embedded name, or Database expression)
`remove_header_item` / `remove_footer_item`	Remove by name; tidies empty `<ReportItems>`

Body composition

Tool	What it edits
`add_body_textbox`	Append a Textbox to `<Body>/<ReportItems>`
`add_body_image`	Append an Image to the body
`remove_body_item`	Remove a named Textbox / Image / Tablix from the body

Snippet templates

Single-call inserts of common report items, programmatically built and appended to the body.

Tool	What it builds
`insert_tablix_from_template`	A basic Tablix mirroring the fixture's shape — header row with the column name as a static label, detail row binding to `=Fields!<column>.Value`. One column per requested field.
`insert_chart_from_template`	A basic Column chart: single category axis grouped by `category_field`, single Y series `=Sum(Fields!<value_field>.Value)`. Change `<Type>` post-insert (Bar / Line / Pie / etc.).

Charts

Refine a chart after insert_chart_from_template (or any existing <Chart>).

Tool	What it edits
`add_chart_series` / `remove_chart_series`	Manage Y-axis `<ChartSeries>`
`set_chart_series_type`	Column / Bar / Line / Area / Pie / ... per series
`set_chart_series_grouping`	Category/series grouping expression
`set_chart_axis`	Category / value axis title, scale, format
`set_chart_legend`	Legend visibility and placement
`set_chart_data_labels`	Toggle and format data labels
`set_chart_title`	Chart title text/expression
`set_chart_palette` / `set_series_color`	Palette name; explicit per-series color

Styling

Tool	What it edits
`set_textbox_style`	Routes properties to the right nested `<Style>` node automatically: box-level (BackgroundColor, Border, VerticalAlign), paragraph-level (TextAlign), run-level (FontFamily, FontSize, FontWeight, Color, Format)
`set_textbox_style_bulk`	Apply one style to many textboxes in a single call
`set_textbox_runs` / `set_textbox_value`	Rich multi-run paragraph content; or replace the value
`find_textboxes_by_style` / `find_textbox_by_value`	Locate textboxes to target follow-up edits
`style_tablix_row`	Style every cell of a tablix row at once (header / detail / footer)
`set_alternating_row_color`	Zebra-stripe a tablix's detail row with `BackgroundColor=IIf(RowNumber(Nothing) Mod 2, "<a>", "<b>")`
`set_conditional_row_color`	Drive detail-row `BackgroundColor` from an expression
`set_image_sizing` / `set_image_source`	Image `<Sizing>`; switch External / Embedded / Database source

Visibility

Tool	What it edits
`set_element_visibility`	Set `<Visibility>` on any named ReportItem (Tablix, Textbox, Image, Rectangle, Subreport, Chart). Group / detail-row visibility have their own tools.

Layout containers

Tool	What it builds
`add_rectangle`	A `<Rectangle>` container (group other items, control page breaks)
`add_list`	A list region (single-column tablix template)
`add_line`	A `<Line>` report item

Positioning & sizing

Move and resize named items in each region. Coordinates are RDL sizes ("1in", "2.5cm", ...).

Tool	What it edits
`set_body_item_position` / `set_header_item_position` / `set_footer_item_position`	`Top` / `Left` of a named item
`set_body_item_size` / `set_header_item_size` / `set_footer_item_size`	`Width` / `Height` of a named item
`set_body_size`	The `<Body>` region's overall height

Interactivity

Tool	What it edits
`set_textbox_action` / `set_image_action` / `set_chart_series_action`	`<Action>`: hyperlink, drill-through, or bookmark
`set_textbox_tooltip`	Textbox `<ToolTip>`
`set_document_map_label`	`<DocumentMapLabel>` for the navigation pane

Pagination

Tool	What it edits
`set_group_page_break`	`<Group><PageBreak>` (Start / End / Between)
`set_repeat_on_new_page`	Repeat a group header/footer on each page
`set_keep_together` / `set_keep_with_group`	Keep-together rendering hints

Parameters (advanced)

Tool	What it edits
`add_parameter` / `remove_parameter` / `rename_parameter`	Manage `<ReportParameter>` elements
`set_parameter_prompt` / `set_parameter_type`	Prompt text; data type (Boolean / DateTime / Integer / Float / Text)
`set_parameter_available_values`	Static `<ParameterValues>` list (strings or `{value, label}` dicts) or `<DataSetReference>` to a lookup dataset
`set_parameter_default_values`	Static `<Values>` list or `<DataSetReference>` (defaults take ValueField only — defaults are values, not display strings)
`update_parameter_advanced`	Toggle the four boolean flags: `multi_value`, `hidden`, `allow_null` (writes `<Nullable>`), `allow_blank`
`reorder_parameters`	Reorder `<ReportParameters>` (controls prompt order)
`set_parameter_layout` / `sync_parameter_layout`	Position parameters in the `<ReportParametersLayout>` grid

Cascading parameters

RDL has no <DependsOn> element — cascading is inferred from =Parameters!X.Value references in a lookup dataset's <QueryParameters>. To wire parameter B to depend on parameter A:

set_parameter_available_values(name="B", source="query", query_dataset="LookupB", ...)
add_query_parameter(dataset_name="LookupB", name="@A", value_expression="=Parameters!A.Value")

Report Builder figures out the dependency graph by parsing those expressions.

Embedded images

Tool	What it edits
`add_embedded_image`	Read a real file off disk, base64-encode it, store under `<EmbeddedImages>`
`list_embedded_images`	Names + MIME types
`remove_embedded_image`	Remove by name; tidies empty `<EmbeddedImages>`

Reference an embedded image with add_*_image(image_source="Embedded", value="<image-name>").

Report lifecycle

Tool	What it does
`create_report`	Scratch-create a minimal valid `.rdl` to start from
`duplicate_report`	Copy a report to a new path
`backup_report` / `restore_from_backup`	Snapshot a report and roll back to it

Expression helpers

These don't mutate the report — they build correct RDL expression strings to pass into other tools (text, filters, conditional styling).

Tool	What it returns
`count_where` / `sum_where`	A `Count`/`Sum` aggregate expression with an inline condition
`iif_format`	An `IIf(...)` expression for conditional values/formatting
`get_expression_reference`	A reference sheet of common RDL expression patterns

Transactions & validation

Batch many edits into one atomic save, and check correctness before/after.

Tool	What it does
`start_editing_transaction` / `commit_editing_transaction` / `cancel_editing_transaction`	Open an in-memory transaction, lint-and-save once, or discard. See docs/TRANSACTIONS.md.
`apply_edits`	Apply a list of tool calls in one transaction
`dry_run_edit`	Preview an edit's effect without writing to disk
`validate_report` / `verify_report`	Structural validation (and opt-in XSD validation against the bundled `reportdefinition.xsd`)
`lint_report`	Surface warnings/errors Report Builder would flag

Raw XML escape hatch

Tool	What it does
`raw_xml_view`	Read the XML under an XPath
`raw_xml_replace`	Replace the XML at an XPath — last resort for anything without a dedicated tool

Power BI specifics

XMLA connection strings

set_datasource_connection writes the canonical form:

Data Source=powerbi://api.powerbi.com/v1.0/myorg/<workspace>;Initial Catalog=<dataset>

workspace_url accepts a bare workspace name (Finance) or a full powerbi:// URL — the tool detects the latter and avoids double-prefixing. DataProvider is set to SQL (the Analysis Services provider id RDL uses for PBI XMLA, despite the misleading name).

DAX queries

DAX bodies are accepted verbatim — pbirb-mcp doesn't parse DAX, so the user (or Report Builder at preview time) is the source of truth for syntax. Empty bodies are rejected up front because Report Builder loads them but errors at preview, which is a worse signal than a clear ValueError here.

PBI paginated reports do not carry <CommandType> for DAX (unlike SSRS where you'd set CommandType=StoredProcedure); these tools never emit it.

Pre-commit hooks (contributors)

pre-commit is in the [dev] extras. After a fresh checkout:

uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/pre-commit install                # one-time — installs the git hook
.venv/bin/pre-commit run --all-files        # one-time — clean any drift

After the hook is installed, every git commit runs ruff format + ruff check (with --fix) + the fast pytest suite. If lint or tests fail the commit is aborted; fix and re-stage before retrying.

To run individual hooks ad-hoc:

.venv/bin/pre-commit run ruff --all-files
.venv/bin/pre-commit run ruff-format --all-files
.venv/bin/pre-commit run pytest-fast --all-files

The full config lives in .pre-commit-config.yaml. Ruff settings (line length, rule selection, per-file ignores) live under [tool.ruff*] in pyproject.toml.

Report Builder install

Power BI Report Builder is a free Microsoft-distributed Windows app:

https://www.microsoft.com/en-us/download/details.aspx?id=105942

Open any .rdl produced by pbirb-mcp directly in Report Builder. The "opens cleanly with no upgrade prompt" check is the actual integration test — the unit tests verify schema correctness, but lxml will round-trip XML that Report Builder's deserialiser still rejects (we hit this twice in the chart-template work; both fixes are documented in the git history).

Architecture

pbirb-mcp/
├── pbirb_mcp_server.py         # Entry point (logging + main())
├── pbirb_mcp/
│   ├── server.py               # JSON-RPC stdio dispatch
│   ├── tools.py                # Tool registry — wires ops into the server
│   ├── core/
│   │   ├── document.py         # RDLDocument: open/save (lxml), atomic write
│   │   ├── xpath.py            # Namespace-aware XPath helpers
│   │   ├── ids.py              # Stable element addressing
│   │   ├── encoding.py         # XML declaration / self-closing-tag fidelity
│   │   ├── transactions.py     # In-memory transaction registry
│   │   └── schema.py           # Structural + opt-in XSD validation
│   ├── ops/                    # One module per RDL concern; wired into tools.py
│   │   ├── reader.py           # describe / get_datasets / get_params / get_tablixes
│   │   ├── datasource.py       # PBI XMLA connection + data-source management
│   │   ├── dataset.py          # DAX body, query params, fields, calc fields, filters
│   │   ├── tablix.py           # Row/column groups, sort, visibility, matrix
│   │   ├── tablix_columns.py   # Add/remove tablix columns
│   │   ├── tablix_cells.py     # Cell span
│   │   ├── tablix_static.py    # Static rows / columns
│   │   ├── tablix_subtotals.py # Subtotal rows / columns
│   │   ├── chart.py            # Chart series, axes, legend, labels, palette
│   │   ├── page.py             # Page setup + orientation
│   │   ├── layout.py           # Pagination (page breaks, keep-together, repeat)
│   │   ├── header_footer.py    # Page header / footer authoring
│   │   ├── body.py             # Body textboxes / images / containers / removal
│   │   ├── positioning.py      # Move / resize named items per region
│   │   ├── templates.py        # Chart + tablix snippet builders
│   │   ├── styling.py          # Textbox styles, runs, bulk, row styling, find
│   │   ├── images.py           # Image sizing / source
│   │   ├── actions.py          # Actions, tooltips, document-map labels
│   │   ├── visibility.py       # Element-level visibility
│   │   ├── parameters.py       # Lifecycle, values, advanced flags, layout
│   │   ├── embedded_images.py  # Base64 image embedding
│   │   ├── expressions.py      # Expression-builder helpers (count/sum/iif)
│   │   ├── filter_types.py     # Filter operator definitions
│   │   ├── clone.py            # duplicate_report
│   │   ├── scratch.py          # create_report
│   │   ├── snapshot.py         # backup / restore
│   │   ├── transactions.py     # start/commit/cancel + apply_edits
│   │   ├── dry_run.py          # dry_run_edit
│   │   ├── validate.py         # validate / verify
│   │   ├── lint.py             # lint_report
│   │   └── escape.py           # raw_xml_view / raw_xml_replace
│   └── schemas/                # Bundled RDL 2016 XSD (reportdefinition.xsd) for opt-in validation
└── tests/
    ├── fixtures/
    │   └── pbi_paginated_minimal.rdl  # Hand-tuned to match Report Builder's emitted style
    └── test_*.py               # 1188 tests — every tool plus round-trip invariants

Hard rules (enforced by tests)

Tests first. Every commit writes failing tests, then makes them pass.
lxml, not stdlib xml.etree. Round-trip fidelity is a feature, not polish. Report Builder reads what's on disk; formatting drift causes silent corruption.
Stable IDs, never indices. Tools take tablix_name + group_name, not column_index: 2. Indices break across multi-step edits.
Atomic save. RDLDocument.save_as writes to <path>.tmp then renames. A failure mid-write never leaves a half-written report.
Round-trip byte-identity is enforced by tests/test_document.py's test_round_trip_byte_identical_to_fixture. A no-op open → save → reopen produces a byte-identical file.

RDL gotchas learned the hard way

<?xml version="1.0" encoding="utf-8"?> uses double quotes, not lxml's default single quotes. Fixed in RDLDocument.save_as via a manual declaration.
Self-closing tags use <Tag /> with a space, not <Tag/>. Fixed via a post-process regex.
The rd: prefix (http://schemas.microsoft.com/SQLServer/reporting/reportdesigner) carries designer metadata Report Builder relies on. Don't strip it; preserve prefixes.
Do not put MustUnderstand="df" on <Report> unless you also declare xmlns:df=....
<ChartCategoryAxes> / <ChartValueAxes> hold <ChartAxis> children directly — there is no <ChartCategoryAxis> / <ChartValueAxis> wrapper.
<ChartMember> requires a <Label> child, even an empty one.
DAX queries live in <DataSet><Query><CommandText>EVALUATE ...</CommandText></Query></DataSet>. No <CommandType> element for DAX (unlike SSRS).

Logging

Two environment variables control the logger:

Variable	Default	Purpose
`PBIRB_MCP_LOG_LEVEL`	`WARNING`	`DEBUG` / `INFO` / `WARNING` / `ERROR`
`PBIRB_MCP_LOG_FILE`	stderr	Path to a log file; otherwise logs go to stderr (where Claude Desktop captures them in its MCP debug pane)

PBIRB_MCP_LOG_LEVEL=DEBUG PBIRB_MCP_LOG_FILE=/tmp/pbirb-mcp.log pbirb-mcp

Development

Running tests

.venv/bin/python -m pytest tests/ -v

The suite is fast (~1.7s for 1188 tests) so re-run on every change.

Smoke testing the live binary

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | .venv/bin/pbirb-mcp

For an end-to-end sanity check, drive an actual mutation against a copy of the bundled fixture:

SCRATCH=$(mktemp -d)/r.rdl
cp tests/fixtures/pbi_paginated_minimal.rdl "$SCRATCH"
.venv/bin/python -c "
from pbirb_mcp.ops.dataset import update_dataset_query
update_dataset_query(path='$SCRATCH', dataset_name='MainDataset',
    dax_body=\"EVALUATE TOPN(10, 'Sales')\")
print('Wrote', '$SCRATCH')
"

Open the resulting file in Power BI Report Builder. Manual verification that an .rdl opens cleanly is the actual integration test — the unit tests catch schema-level mistakes, but only Report Builder catches deserialiser nits.

Adding a new tool

Write tests first under tests/test_*.py.
Implement in the appropriate pbirb_mcp/ops/*.py module (or create a new one).
Register in pbirb_mcp/tools.py with a clear description and strict inputSchema.
Run the full suite and a JSON-RPC smoke against the fixture.
Open the modified RDL in Report Builder.

The commit-by-commit history shows the pattern in practice.

Releases

CHANGELOG.md tracks every release in Keep a Changelog format. Releases are also published as GitHub Releases and to PyPI.

Versions follow SemVer adapted for an MCP tool surface — see CONTRIBUTING.md § Versioning.

Contributing

PRs welcome. CONTRIBUTING.md covers dev setup, the hard rules (tests-first, lxml only, stable IDs, atomic save, byte-identity round-trip, smoke in Report Builder), the SemVer-for-MCP bump table, and the PR review checklist.

Bug reports and tool proposals: please use the issue templates. For security issues, see SECURITY.md. All participants are expected to follow the Code of Conduct.

Acknowledgments

The existing bethmaloney/rdl-mcp server pioneered the MCP-over-RDL pattern but is scoped to SSRS: column metadata, basic parameter management, stored-procedure swap. Power BI paginated reports use the same RDL 2016 schema as SSRS, but:

Data sources are Power BI XMLA endpoints, not SQL Server.
Queries are DAX, and the upstream tool exposes no body-edit (only stored-procedure name swap, useless here).
Report Builder is picky about XML round-tripping — formatting drift, namespace prefix loss, or unrecognised MustUnderstand attributes cause silent corruption or "this report needs to be upgraded" prompts.

pbirb-mcp is built around lxml so a no-op edit produces a byte-identical file, addresses every element by stable name (never index), and treats "opens cleanly in Report Builder" as the actual integration test.

mcp-name: io.github.mafaq229/pbirb-mcp

Available Tools

143 tools

add_body_imageB

Add an Image to /. image_source: External (URL), Embedded (EmbeddedImage Name), Database (=Fields!Photo.Value).

ParametersJSON Schema

Name	Required	Description	Default
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes
`value`	Yes
`width`	Yes
`height`	Yes
`image_source`	Yes

TDQS

B3.1/5.0

Behavior2/5

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

With no annotations, the description carries the full burden for behavioral disclosure. It only mentions adding an image and the source types, omitting critical traits like whether images can be overwritten, required permissions, or side effects on existing items. No return value or error conditions are described.

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 description is a single sentence with parenthetical examples, which is concise and to the point. It could benefit from a slightly more structured format (e.g., listing parameters), but the brevity is appropriate for the tool's simplicity.

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

Completeness1/5

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

For a tool with 8 required parameters and no output schema or annotations, the description is severely incomplete. It fails to explain what each parameter represents (e.g., path vs value, coordinate system for top/left), leaving significant gaps for an agent to fill. The completeness is inadequate for correct invocation.

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

Parameters2/5

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

Schema coverage is 0%, yet the description only explains the 'image_source' parameter by listing its enum options. The other 7 required parameters (top, left, name, path, value, width, height) receive no semantic explanation, forcing the agent to rely solely on parameter names without context.

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 clearly states 'Add an Image to <Body>/<ReportItems>' with concrete verb 'Add', specific resource 'Image', and location. It also explains the three image_source options, providing immediate clarity on what the tool does and differentiating it from other add tools.

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

Usage Guidelines3/5

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

The description implies usage through the image_source enum but provides no explicit guidance on when to use this tool over alternatives like 'add_embedded_image' or other add tools. No exclusion criteria or prerequisites are mentioned, leaving the agent to infer usage context.

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

add_body_textboxA

Add a Textbox to /. text accepts static strings or RDL expressions (e.g. =Globals!ReportName). Coexists with the existing tablix; rejects names already in use. Pass raw text — encoding is handled; don't pre-encode XML entities (use & not &, including for the VB.NET string-concat operator in expressions).

ParametersJSON Schema

Name	Required	Description
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes
`text`	Yes	Static text or RDL expression (=...).
`width`	Yes
`height`	Yes

TDQS

A3.6/5.0

Behavior4/5

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

Given no annotations, the description usefully discloses that duplicate names are rejected and encoding is handled, giving the agent key behavioral expectations.

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?

Three concise sentences efficiently convey essential information without redundancy; the first sentence front-loads the purpose.

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

Completeness2/5

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

Without annotations or output schema, the description is insufficient: it omits crucial details like parameter units (top/left/width/height), the meaning of 'path', and name constraints, leaving the agent underinformed.

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

Parameters2/5

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

Schema coverage is only 14%; the description adds value only for the 'text' parameter (encoding detail), but 6 out of 7 parameters (path, name, top, left, width, height) lack any additional semantics in either schema or description.

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 clearly states the action 'Add a Textbox' and the precise location '<Body>/<ReportItems>', which effectively differentiates it from sibling tools like add_header_textbox or add_footer_textbox.

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

Usage Guidelines3/5

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

The description provides some usage guidance (handling of expressions, duplicate names, encoding) but does not explicitly contrast with alternatives or specify conditions for use.

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

add_calculated_fieldA

Append a calculated to the named dataset. Calculated fields carry an expression () instead of a column reference (); use them for derived fields like Total = Amount * Quantity that aren't in the source query but should be available via Fields!Name.Value. Refuses if a field of the same name already exists.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`expression`	Yes	RDL expression, e.g. '=Fields!Amount.Value * Fields!Quantity.Value'.
`field_name`	Yes
`dataset_name`	Yes

TDQS

A3.7/5.0

Behavior3/5

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

With no annotations provided, the description carries the full burden. It discloses a key behavioral trait: refusal on duplicate field names. However, it does not mention whether an editing transaction is required (common among sibling tools), authentication needs, or error handling, leaving gaps in transparency.

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?

Two sentences, no redundant information. The purpose is front-loaded in the first sentence, followed by usage context and a constraint. Efficient and to the point.

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

Completeness3/5

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

Given no output schema and 4 required params, the description provides essential context (refusal on duplicates, expression usage) but omits prerequisites (e.g., editing transaction status), success/failure behavior, or return value. For a tool with this complexity, it is adequate but not fully comprehensive.

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

Parameters2/5

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

Schema description coverage is only 25% (only 'expression' has a description). The description adds context about expression semantics (using Fields!Name.Value) but does not explain 'path', 'field_name', or 'dataset_name' individually. For a tool with 4 params and low schema coverage, more parameter guidance is needed.

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 clearly states the action ('Append a calculated <Field> to the named dataset') and identifies the specific resource type (calculated field). It distinguishes from sibling tools like add_dataset_field by explicitly contrasting calculated fields with column references, and from remove_calculated_field by its append action.

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?

Provides explicit guidance on when to use calculated fields (derived fields like Total = Amount * Quantity not in source query) and mentions a constraint (refuses if same name exists). Lacks explicit 'when not to use' or alternatives, but the context is clear enough for effective selection.

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

add_chart_seriesA

Append a new to a named chart. value_field is the dataset field whose Sum becomes the Y expression (=Sum(Fields!.Value)). series_type defaults to Column; combine series of different types in one chart for combo charts (e.g. Bar + Line). series_subtype defaults to Plain. Refuses if series_name already exists.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`chart_name`	Yes
`series_name`	Yes
`series_type`	No	Column / Bar / Line / Area / Pie / Doughnut / Range / Scatter / Bubble / Stock / Polar / Radar / Funnel / Pyramid
`value_field`	Yes
`series_subtype`	No	Plain / Stacked / PercentStacked / Smooth / Exploded / SmoothLine / 100 / Line / Spline

TDQS

A3.8/5.0

Behavior3/5

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

Discloses refusal condition and defaults, but doesn't specify prerequisites (chart existence), return value, or required permissions. With no annotations, more transparency would be beneficial.

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?

Four sentences, clear front-loading, no redundant information. Could be slightly more streamlined but effective.

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

Completeness3/5

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

Covers core behavior and error condition, but misses prerequisites (chart existence), return value, and broader usage context. Adequate but not comprehensive given no output schema.

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?

Adds significant meaning beyond schema: explains value_field's role in Y expression, defaults for series_type and series_subtype, and combo chart capability. Only path and chart_name are left implicit.

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 clearly states the action: 'Append a new <ChartSeries> to a named chart.' It explains key parameters and distinguishes from siblings like set_chart_series_type and remove_chart_series by focusing on adding new series.

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

Usage Guidelines3/5

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

Usage context is implied (adding new series, refusal if exists), but no explicit guidance on when to use this tool versus alternatives like set_chart_series_type or set_chart_series_action.

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

add_column_groupA

Add a column group that wraps the current top-level column hierarchy. Inserts a matching column at body column 0 (default 1in width) and a header cell at column 0 of every existing row with the group expression in the topmost cell. Mirrors add_row_group on the column axis. parent_group nesting is reserved for a future commit and currently raises NotImplementedError.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`group_name`	Yes
`tablix_name`	Yes
`parent_group`	No
`group_expression`	Yes	RDL expression, e.g. =Fields!Region.Value

TDQS

A4.2/5.0

Behavior4/5

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

Describes insertion of column and header cells, default width, and that parent_group raises NotImplementedError. Without annotations, it carries full burden and does so fairly well, though could mention prerequisites.

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

Conciseness5/5

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

Two concise sentences with a third for a key limitation. No wasted words, front-loaded purpose.

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

Completeness4/5

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

Given no output schema and no annotations, description provides sufficient context for typical use, covering effect and limitations, though missing parameter details.

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

Parameters3/5

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

Only 20% schema coverage; description explains parent_group limitation and implies group_expression usage but does not explain path, group_name, or tablix_name. Adds some value but insufficient for low coverage.

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 clearly states the verb 'add' and resource 'column group'. It distinguishes from siblings by mentioning it mirrors add_row_group on the column axis. The effect is explained in detail.

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?

Clear context that it's the column-axis counterpart of add_row_group, but lacks explicit when-not-to-use or alternatives beyond add_row_group.

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

add_dataset_fieldA

Append a data-bound to a dataset's block. Writes data_field (and optional rd:TypeNametype_name). Distinct from add_calculated_field which writes for derived fields. Use after rewriting the DAX to declare a new column that came back from the query but isn't yet in . Refuses on duplicate field name.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`type_name`	No	.NET type, e.g. 'System.String', 'System.DateTime', 'System.Decimal'. Optional.
`data_field`	Yes	Source column reference, e.g. 'Sales[ProductID]' or '[Region]' (the form depends on DAX shape).
`field_name`	Yes
`dataset_name`	Yes

TDQS

A3.8/5.0

Behavior3/5

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

No annotations are provided, so the description must carry the burden. It discloses that the tool writes specific XML elements (<DataField> and optional <rd:TypeName>) and refuses if the field name duplicates. However, it omits details like potential side effects on existing fields, validation triggers, or required permissions.

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

Conciseness5/5

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

The description is three sentences long, each serving a purpose: stating the action, detailing the XML written, and providing usage context. It is front-loaded with the core purpose and wastes no words.

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

Completeness3/5

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

For a tool with 5 parameters and no output schema, the description provides a usage scenario but fails to document 3 parameters. It adequately explains the behavior around duplicates and the written elements, but the missing parameter details reduce completeness.

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

Parameters2/5

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

Schema coverage is only 40% (descriptions for type_name and data_field exist in schema). The description adds valuable examples for data_field (e.g., 'Sales[ProductID]') and explains type_name as .NET type. However, the parameters path, field_name, and dataset_name remain completely unexplained in both schema and description, which is insufficient given the low coverage.

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 clearly states the tool appends a data-bound <Field> to a dataset's <Fields> block and explicitly distinguishes it from add_calculated_field by noting that it writes <DataField> rather than <Value>. The verb 'Append' and resource 'dataset's <Fields> block' are precise.

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?

The description advises to use after rewriting the DAX to declare a new column from the query, which gives good context. It also mentions the refusal on duplicate field name. However, it does not explicitly discuss when not to use or list alternative siblings beyond the one mentioned.

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

add_dataset_filterA

Append a to the named dataset's block. operator ∈ Equal / NotEqual / GreaterThan / LessThan / GreaterThanOrEqual / LessThanOrEqual / Like / In / Between / TopN / BottomN / TopPercent / BottomPercent. values must be non-empty (single-value filters use a one-element list). Returns the new filter's index for later removal. Optional field_format wraps the expression as Format(, fmt) to coerce typed fields for string-parameter comparison. Response includes warnings for field/parameter type mismatches detected via best-effort cross-check.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`values`	Yes
`operator`	Yes
`expression`	Yes	FilterExpression — usually a Fields! reference.
`dataset_name`	Yes
`field_format`	No	Optional format string (e.g. 'MMM, yyyy') wrapping the expression as Format(<body>, '<fmt>').

TDQS

A4.5/5.0

Behavior4/5

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

Despite no annotations, the description reveals key behaviors: it returns the new filter index, includes best-effort type mismatch warnings, and specifies value must be non-empty. It does not mention permissions or idempotency, but covers the main effects.

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

Conciseness5/5

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

The description is a single, well-structured paragraph. Every sentence adds value: main action, operator list, values constraint, return intent, field_format, and warnings. No wasted words.

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

Completeness4/5

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

The description covers the return value (filter index), all parameter nuances, and response warnings. It lacks details on path or dataset_name format, but given no output schema, it is sufficiently complete for a 6-parameter tool.

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?

The description adds substantial meaning beyond the schema: it explains operator enumeration, values constraint (non-empty, single-value as one-element list), field_format wrapping, and the 'Fields!' expression convention. With only 33% schema coverage, this compensates effectively.

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 clearly states the tool appends a <Filter> to a dataset's <Filters> block, specifies operator options, value constraints, and return value, distinguishing it from siblings like remove_dataset_filter and add_tablix_filter.

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?

The description implies use for dataset filters (vs tablix filters) but does not explicitly exclude or compare with alternatives like add_tablix_filter. It provides clear context for when to use this tool.

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

add_data_sourceA

Create a new for a Power BI XMLA endpoint. workspace_url accepts a bare workspace name or a full powerbi:// URL. Generates a fresh rd:DataSourceID GUID. Refuses if a DataSource of the same name already exists. provider='sql' (default) emits the legacy DataProvider=SQL + powerbi:// ConnectString + rd:SecurityType shape; provider='pbidataset' emits the modern PBI Desktop shape — DataProvider=PBIDATASET, pbiazure:// ConnectString with ClaimsToken auth, plus rd:PowerBIWorkspaceName / rd:PowerBIDatasetName siblings, no rd:SecurityType.

ParametersJSON Schema

Name	Required	Default
`name`	Yes
`path`	Yes
`provider`	No	sql
`dataset_name`	Yes
`workspace_url`	Yes
`integrated_security`	No

TDQS

A3.9/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses generation of a new GUID, duplicate refusal, and detailed provider shape behaviors. However, it does not mention authentication requirements or side effects on the report.

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 description is dense but efficient, front-loading the main action and then providing details. It could be slightly more concise, but every sentence adds value without redundancy.

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

Completeness4/5

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

Given 6 parameters, no output schema, and no annotations, the description provides substantial context about behavior and constraints. Missing details include return value and full parameter documentation, but it is relatively complete for a creation tool.

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

Parameters3/5

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

The input schema has 0% description coverage, so the description must compensate. It explains workspace_url and provider well, but other parameters (name, path, dataset_name, integrated_security) are not described. Partial coverage leaves gaps.

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 clearly states the tool creates a new DataSource for Power BI XMLA endpoint, with specific details on workspace_url and provider shapes. It distinguishes from sibling tools like remove_data_source or rename_data_source by focusing on creation.

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

Usage Guidelines3/5

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

The description mentions a constraint (refuses if name exists) but does not explicitly guide when to use this vs alternatives like set_datasource_connection or update. Usage context is implied but not contrasted with siblings.

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

add_embedded_imageA

Read a real image file off disk, base64-encode it, and store it under . Reference it later with image_source='Embedded' + value=. Supported MIME types: image/bmp, image/gif, image/jpeg, image/png, image/x-png. The file's magic bytes are sniffed and must match mime_type — claiming PNG bytes as image/jpeg is rejected here rather than letting Report Builder fail at preview time.

ParametersJSON Schema

Name	Required	Description
`name`	Yes
`path`	Yes
`mime_type`	Yes
`image_path`	Yes	Filesystem path to the source image.

TDQS

A3.9/5.0

Behavior4/5

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

Discloses base64 encoding, storage location, magic byte sniffing, and rejection of mismatched types. No annotations provided, so description carries burden well, though security/permissions not mentioned.

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?

Single paragraph front-loads main action, fairly concise but slightly run-on. Could be broken into clearer sentences.

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

Completeness3/5

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

Covers main workflow and validation, but leaves ambiguity about two path parameters. No output schema, yet function is adequately described for typical use.

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

Parameters2/5

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

Schema coverage is low (25%) and description only explains 'name' and 'mime_type' partially. It fails to clarify the difference between required parameters 'path' and 'image_path', leading to ambiguity.

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?

Description clearly states the tool reads an image file, base64-encodes it, stores it under EmbeddedImages, and lists supported MIME types. It distinguishes from siblings like 'add_body_image' by focusing on embedding rather than placing in body, though not explicitly.

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?

Description explains when to use (importing image files for embedding) and how to reference later, but does not explicitly mention when not to use or alternatives like 'add_body_image'.

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

add_footer_imageC

Same as add_header_image, for .

ParametersJSON Schema

Name	Required	Description
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes
`value`	Yes	URL for External, embedded-image name for Embedded, or =Fields!X.Value for Database.
`width`	Yes
`height`	Yes
`image_source`	Yes

TDQS

C2/5.0

Behavior2/5

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

No annotations are provided, and the description does not disclose behavioral traits such as whether the operation is destructive, requires permissions, or how the image is placed. The brief reference to 'add_header_image' does not compensate for the missing transparency.

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

Conciseness3/5

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

The description is extremely concise (one short sentence), but it lacks substance. Conciseness is present, but the content is insufficient, resulting in a borderline adequate score.

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

Completeness1/5

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

Given the complexity of 8 required parameters, no output schema, and no annotations, the description is severely incomplete. It provides almost no context about how the tool works, what the parameters mean, or what happens after invocation.

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

Parameters2/5

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

With only 13% schema description coverage (only 'value' has a description), the description adds no parameter details. It fails to explain critical parameters like 'top', 'left', 'width', 'height', or the enum 'image_source'. The schema's limited descriptions are not supplemented.

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

Purpose2/5

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

The description says 'Same as add_header_image, for <PageFooter>.' This is vague and relies on understanding another tool's description. It does not explicitly state that the tool adds an image to a page footer, leaving the purpose unclear without external context.

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

Usage Guidelines2/5

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

The description offers no guidance on when to use this tool versus alternatives. It does not specify scenarios, exclusions, or compare with sibling tools like add_footer_textbox or add_body_image.

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

add_footer_textboxC

Same as add_header_textbox, for .

ParametersJSON Schema

Name	Required	Description
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes
`text`	Yes	Static text or RDL expression (=...).
`width`	Yes
`height`	Yes

TDQS

C2.4/5.0

Behavior2/5

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

No annotations are provided, and the description gives no insight into side effects, permissions, or behavior beyond adding a textbox. Minimal transparency for a tool that likely modifies report structure.

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

Conciseness3/5

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

The description is very short (one sentence), which is concise but lacks necessary details for a tool with multiple parameters. It earns a middle score for being brief but under-specified.

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

Completeness2/5

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

Given the complexity of adding a textbox to a report footer (position, size, name, path), the description is inadequate. No explanation of positioning format or required properties, making it incomplete.

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

Parameters2/5

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

The input schema has 7 required parameters with only one (text) having a description. The description adds no further semantic meaning to the parameters, leaving their format and constraints unclear.

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

Purpose3/5

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

The description indicates the tool adds a textbox to the footer area, but it requires knowledge of 'add_header_textbox' to fully understand the operation. The purpose is somewhat clear but not self-contained.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like 'add_header_textbox' or 'add_body_textbox'. The description only states it's the same as the header version for the footer, without context on when which is appropriate.

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

add_header_imageB

Add an Image to /. image_source is External (URL in value), Embedded (EmbeddedImage Name in value), or Database (=Fields!Photo.Value-style expression).

ParametersJSON Schema

Name	Required	Description
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes
`value`	Yes	URL for External, embedded-image name for Embedded, or =Fields!X.Value for Database.
`width`	Yes
`height`	Yes
`image_source`	Yes

TDQS

B3.3/5.0

Behavior2/5

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

With no annotations, the description must fully disclose behavior. It explains image_source options but does not mention side effects, permissions required, or whether it overwrites existing images. The description is minimal beyond parameter hints.

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 description is one sentence with relevant info, no filler. It could be slightly more structured but is efficient.

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

Completeness2/5

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

The tool has 8 required parameters and no output schema, but the description only covers image_source and value. It omits important details like measurement units for top/left/width/height and naming conventions for path and name. The description is incomplete for proper invocation.

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

Parameters3/5

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

Schema description coverage is only 13% (only 'value' described). The description adds meaning to image_source and value (explaining the three sources), but does not explain top, left, width, height, name, or path. It partially compensates but not sufficiently for low coverage.

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 clearly states the tool adds an image to PageHeader/ReportItems, uses specific verb-add and resource-header image, and differentiates from siblings like add_body_image and add_footer_image by specifying the header context.

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

Usage Guidelines3/5

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

The description implies usage for adding images to headers but does not explicitly state when to use this tool over alternatives like add_body_image or add_footer_image, nor does it mention any prerequisites or exclusions.

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

add_header_textboxA

Add a Textbox to /. text accepts static strings or RDL expressions (=Parameters!DateFrom.Value). Pass raw text — encoding is handled; don't pre-encode XML entities (use & not &, including for the VB.NET string-concat operator in expressions).

ParametersJSON Schema

Name	Required	Description
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes
`text`	Yes	Static text or RDL expression (=...).
`width`	Yes
`height`	Yes

TDQS

A3.7/5.0

Behavior3/5

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

Discloses encoding behavior and expression syntax, which adds value beyond the schema. However, without annotations, it does not cover side effects, authorization, or effects on existing items.

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

Conciseness5/5

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

Two succinct sentences that are well-structured and front-loaded with the key purpose. Every sentence adds essential information with no redundancy.

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

Completeness2/5

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

Despite moderate complexity (7 required parameters, no annotations), the description only fully covers one parameter. Missing details on prerequisites (e.g., editing transaction), behavior on duplicate names, and return values.

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

Parameters2/5

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

Only describes the text parameter in detail; the other six parameters (top, left, name, path, width, height) lack any description, and schema coverage is only 14%.

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 clearly states the action ('Add') and resource ('Textbox') with a specific target ('PageHeader'). It effectively distinguishes from sibling tools like add_body_textbox and add_header_image.

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?

Provides clear guidelines on using the text parameter (static or expression, encoding handling), but lacks explicit when-not-to-use or comparisons to alternatives like set_textbox_value.

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

add_lineA

Add a to /. RDL Line semantics: top/left is the start point; width/height is the offset (vector) to the end point — horizontal line uses height='0in', vertical uses width='0in'. Optional color, line_thickness ('1pt' default), line_style (Solid/Dashed/Dotted/Double/etc.). Returns {name, kind: 'Line'}.

ParametersJSON Schema

Name	Required	Description	Default
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes
`color`	No
`width`	Yes
`height`	Yes
`line_style`	No
`line_thickness`	No

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations, description provides key behavioral details: coordinate interpretation, optional styling parameters, and return structure. Lacks disclosure of error conditions or permission requirements, but sufficient for a simple add operation.

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

Conciseness5/5

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

Three sentences, no extraneous content. Front-loaded with purpose, followed by critical coordinate semantics and optional parameters. Efficient.

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

Completeness4/5

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

Covers purpose, coordinate system, optional parameters, and return value. Lacks details on path existence validation or error handling, but adequate given tool's simplicity. No output schema, so return info is helpful.

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 has 0% description coverage, but description adds substantial meaning: explains top/left/width/height as start+offset, line_thickness default, line_style enum, and return shape. This goes far beyond the raw schema.

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?

Clearly states action ('Add a <Line>'), target resource ('<Body>/<ReportItems>'), and distinguishes from siblings like add_body_image or add_body_textbox by specifying the line element. Includes coordinate semantics and optional parameters.

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

Usage Guidelines3/5

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

Describes coordinate system (top/left as start, width/height as offset) which aids correct usage, but does not explicitly state when to use this tool over alternatives like add_rectangle, nor mention prerequisites or restrictions.

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

add_listA

Add a List (single-cell repeating Tablix) bound to a dataset. RDL has no distinct element — Report Builder's List is a Tablix with one column, one detail row, and a Rectangle inside the cell. Items placed in the rectangle repeat once per dataset row. The inner rectangle is named '_Rect' for subsequent lookup. Returns {name, kind: 'Tablix', dataset, rectangle}.

ParametersJSON Schema

Name	Required	Description	Default
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes
`width`	Yes
`height`	Yes
`dataset_name`	Yes

TDQS

A4/5.0

Behavior4/5

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

With no annotations, the description discloses key behaviors: the List is implemented as a Tablix with specific structure, the inner rectangle is named, and returns relevant fields. It does not cover side effects or permissions but provides substantial transparency.

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

Conciseness5/5

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

The description is concise, with every sentence adding value. It explains the RDL concept, the tool's behavior, and return value in a compact paragraph.

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

Completeness3/5

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

Given the complexity (7 required params, no output schema, many siblings), the description provides essential information but lacks parameter details. It is adequate but has clear gaps.

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

Parameters2/5

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

The input schema has 7 required parameters with 0% description coverage. The description does not explain any parameter details (e.g., format of top/left). Only dataset_name is implied by context. This leaves the agent with limited guidance.

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 clearly states the tool adds a List (single-cell repeating Tablix) bound to a dataset. It explains the RDL representation and distinguishes from sibling tools like add_tablix_column.

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?

The description provides context on when to use this tool (to create a repeating item per dataset row). It does not explicitly exclude alternatives but explains the List's nature, giving the agent enough information to choose appropriately.

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

add_parameterA

Create a new ReportParameter with a minimal valid declaration. Appends to (creating it if absent). Pair with set_parameter_available_values / set_parameter_default_values afterwards for value lists. Booleans are only emitted when an explicit value is supplied.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`type`	Yes
`hidden`	No
`prompt`	No
`allow_null`	No
`allow_blank`	No
`multi_value`	No

TDQS

A3.9/5.0

Behavior4/5

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

With no annotations, the description discloses key behaviors: appending to <ReportParameters> (creating if absent) and the nuance that booleans are only emitted when an explicit value is supplied. This adds meaningful behavioral context beyond the schema.

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

Conciseness5/5

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

Three concise sentences, each adding distinct value: core purpose, post-creation workflow, and a behavioral caveat. No wasted words, well front-loaded.

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

Completeness2/5

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

Given 8 parameters, no output schema, and no schema descriptions, the description is too minimal. It omits explanations for required parameters (path, name, type) and optional ones (hidden, prompt, etc.), leaving the agent underinformed.

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

Parameters2/5

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

Schema has 8 parameters with 0% description coverage. The description only hints at boolean behavior for the 'type' parameter. It does not explain 'name', 'path', 'hidden', 'prompt', or other fields, leaving the agent to infer their meaning.

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 clearly states 'Create a new ReportParameter with a minimal valid declaration', using a specific verb and resource. It distinguishes from sibling 'add_' tools by naming the resource type and mentioning companion tools like set_parameter_available_values.

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?

The description explains the tool's role in creating minimal declarations and directs to use set_parameter_available_values / set_parameter_default_values for value lists. It implies when to use (initial creation) but lacks explicit when-not-to-use or alternatives for updating existing parameters.

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

add_query_parameterA

Add a binding to a dataset's query. Use to wire report parameters into DAX (e.g. =Parameters!DateFrom.Value).

PBIDATASET parameter naming rule: in DAX/, write @MyParam (with @). In , write MyParam (no @). SQL/MDX use @ in both places. This tool detects the dataset's provider and AUTO-STRIPS a leading @ from name for PBIDATASET datasets, returning {normalised: true, warning: ...}. Pass force_at_prefix=true to override (rare; needed for some RSCustomDaxFilter patterns).

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`dataset_name`	Yes
`force_at_prefix`	No
`value_expression`	Yes

TDQS

A4/5.0

Behavior4/5

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

With no annotations provided, the description takes on the burden of disclosing behavior. It explains the auto-stripping of '@' for PBIDATASET datasets, the normalised flag, and the force_at_prefix override. This provides good insight into the tool's behavior beyond its basic function.

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 description is front-loaded with the primary purpose and includes a detailed second paragraph on behavior. It is efficient without being verbose. Minor improvements could make it even more concise.

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

Completeness3/5

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

Given the absence of annotations and output schema, the description covers the key behavioral aspects and parameter nuances. However, it lacks information on error handling, prerequisites (e.g., dataset existence), and return values beyond the normalised flag. It is reasonably complete but has gaps for a tool with 5 parameters.

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

Parameters3/5

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

The input schema has 0% description coverage, so the description must compensate. It explains the naming convention for the 'name' parameter and the role of value_expression via example. However, it does not explicitly describe all parameters (path, dataset_name), relying on their names. The explanation adds some value but is not fully comprehensive.

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 clearly states 'Add a <QueryParameter> binding to a dataset's query' and provides an example of wiring report parameters into DAX. This distinguishes it from sibling tools like add_parameter or update_query_parameter.

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?

The description explains when to use the tool (to wire report parameters into DAX) and provides an example. It also covers the rare override case with force_at_prefix. However, it does not explicitly state when not to use it or mention alternatives like update_query_parameter.

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

add_rectangleA

Add a to /. With no contained_items the rectangle is empty (a visual frame). With contained_items=[name1, name2, ...], each named body item is MOVED into the rectangle's and its / recalculated so the on-screen position is preserved. Refuses on duplicate name or if any contained_item isn't in /. Returns {name, kind: 'Rectangle', moved}.

ParametersJSON Schema

Name	Required	Description
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes
`width`	Yes
`height`	Yes
`contained_items`	No	Optional names of existing body items to move into the rectangle. Omit or pass [] for an empty rectangle (visual frame).

TDQS

A3.9/5.0

Behavior4/5

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

With no annotations, the description carries full burden. It details behavior: moves items, recalculates positions, and refuses on duplicates or invalid items. Return value is specified. However, it does not mention potential side effects like moving items affecting other references.

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

Conciseness5/5

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

Two sentences efficiently convey core action, two modes, and return value. No wasted words; well-structured for quick comprehension.

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

Completeness3/5

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

Given 7 parameters and no output schema, the description covers main scenarios but leaves gaps: path parameter unexplained, format of top/left/width/height not specified. Adequate but not comprehensive.

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

Parameters3/5

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

Schema coverage is low (14%). The description adds context for contained_items (moving items) and implies positional parameters are string expressions, but does not fully explain each parameter's format or constraints. Partially compensates for missing schema descriptions.

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 clearly states the tool adds a Rectangle to Body/ReportItems, distinguishing between empty frame and moving items. It also specifies refusal conditions, making it distinct from sibling tools like add_body_image or add_line.

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

Usage Guidelines3/5

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

The description explains what the tool does but lacks explicit guidance on when to use it versus alternatives. It does not mention when not to use it or provide comparisons to similar tools.

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

add_row_groupA

Add a row group that wraps the entire current top-level row hierarchy. Inserts a matching group-header row at body row 0 with the group expression in the first cell. parent_group (nesting under an existing group) is reserved for a future commit and currently raises NotImplementedError.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`group_name`	Yes
`tablix_name`	Yes
`parent_group`	No
`group_expression`	Yes	RDL expression, e.g. =Fields!Region.Value

TDQS

A4.1/5.0

Behavior4/5

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

The description discloses that it inserts a matching group-header row at body row 0 with the group expression in the first cell, and that parent_group raises NotImplementedError. This provides clear behavioral context beyond the input schema.

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

Conciseness5/5

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

The description is two sentences, front-loaded with the main action, and contains no redundant information. Every sentence adds value.

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

Completeness3/5

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

Given no annotations or output schema, the description explains the core functionality but lacks details on error conditions, return value, and full parameter descriptions. It is adequate but not comprehensive.

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

Parameters3/5

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

The input schema has only 20% description coverage (only group_expression has a description). The description adds an example for group_expression and explains parent_group behavior, but does not clarify the purpose of path, group_name, or tablix_name.

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 states 'Add a row group that wraps the entire current top-level row hierarchy' which is a specific verb and resource. It clearly distinguishes from sibling tools like add_column_group and add_static_row by focusing on row grouping.

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?

The description indicates it operates on the 'entire current top-level row hierarchy' and notes that parent_group is reserved for future use, implying only top-level grouping is possible. However, it does not explicitly mention alternatives like add_column_group for column grouping.

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

add_static_columnA

Add a static (no-group) column to a tablix. Each cell holds literal text. cells is a list of strings, one per body row (top to bottom); shorter list = blank trailing cells, longer list errors. Cell textboxes are named column_name (row 0) and column_name_ (others). position is 0-indexed; default appends. width defaults to 1in.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`cells`	No
`width`	No
`position`	No
`column_name`	Yes
`tablix_name`	Yes

TDQS

A3.8/5.0

Behavior4/5

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

With no annotations, the description carries the burden. It details cell behavior (shorter list = blank trailing, longer = error), naming conventions, default positions and width. However, it omits mentioning required editing transactions or conflict handling.

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 description is five sentences, front-loaded with purpose. It is mostly concise, though it could trim phrasing like '(top to bottom)' which is implicit in row order. No unnecessary words.

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

Completeness3/5

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

Given 6 parameters, no output schema, and no annotations, the description adequately covers core behavior but misses context like editing session requirements, error handling, and relationship to sibling tools. It does not explain return values.

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 0%, so the description must compensate. It explains cells (list of strings, per row, errors on longer list), position (0-indexed, default appends), and width (defaults to 1in). Three of six parameters gain meaning; path, tablix_name, column_name are left mostly implicit.

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 clearly states 'Add a static (no-group) column to a tablix' with a specific verb and resource. It distinguishes itself from siblings like add_calculated_field or add_tablix_column by emphasizing 'static' and 'no-group'.

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

Usage Guidelines2/5

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

The description provides no explicit guidance on when to use this tool vs alternatives like add_tablix_column or add_calculated_field. It does not mention prerequisites or when not to use it.

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

add_static_rowA

Add a static (no-group) row to a tablix. Each cell holds literal text. cells is a list of strings, one per body column (left to right); shorter list = blank trailing cells, longer list errors. Cell textboxes are named row_name (col 0) and row_name_ (others) — unique report-wide so row_name must not clash with any existing textbox. position is 0-indexed; default appends. height defaults to 0.25in.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`cells`	No
`height`	No
`position`	No
`row_name`	Yes
`tablix_name`	Yes

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations, the description provides extensive behavioral details: cells list length behavior, naming convention for textboxes, uniqueness requirement for row_name, default append for position, and default height. It fully discloses what happens during invocation, covering all critical aspects.

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

Conciseness5/5

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

The description is four sentences, each earning its place. The purpose is front-loaded, followed by parameter details and behavioral constraints. No redundant information, efficient and well-structured.

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?

Given no output schema and no annotations, this description is complete. It covers all parameter semantics, behavioral traits, and usage context. For a 6-parameter tool, it leaves no significant gaps, enabling correct selection and invocation.

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 description coverage is 0%, so the description compensates fully. It explains cells (list of strings, per column, behavior on size mismatch), row_name (textbox naming, uniqueness), position (0-indexed, default appends), and height (default 0.25in). Path and tablix_name are standard but clear from context. This adds substantial meaning beyond the schema.

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 clearly states the tool's purpose: 'Add a static (no-group) row to a tablix.' It specifies that cells hold literal text, distinguishing it from grouped rows (add_row_group) or subtotal rows (add_subtotal_row). This precise verb-resource pairing with differentiation makes it highly clear.

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?

The description explains that the row is static and no-group, implying it should be used for literal text rows. However, it does not explicitly exclude alternatives like add_row_group or add_subtotal_row. The context is clear but lacks explicit when-not-to-use guidance, hence a 4.

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

add_subtotal_columnA

Column-axis mirror of add_subtotal_row. Adds a static TablixMember inside the column-group's , a new in TablixBody, and a cell at the new column index in every body row. aggregates is a list of {row, expression} entries where row is the 0-based body row index; rows not listed get blank cells. position='after' (default — canonical Grand Total slot, appends to the right of the column group) or 'before' (prepends to the group's left edge). width defaults to '1in'. Group must have been added via add_column_group.

ParametersJSON Schema

Name	Required	Default
`path`	Yes
`width`	No	1in
`position`	No	after
`aggregates`	Yes
`group_name`	Yes
`tablix_name`	Yes

TDQS

A4.2/5.0

Behavior3/5

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

The description explains the structural changes made (TablixMember, TablixColumn, cells) and the aggregates parameter. Since no annotations are provided, the description carries the full burden. It does not cover error conditions, destructive nature (e.g., if a subtotal already exists), or permissions, which would be helpful for a mutation tool.

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

Conciseness5/5

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

The description is concise at 4 sentences, well-structured, and front-loaded with the core purpose. Every sentence adds necessary information without redundancy.

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

Completeness3/5

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

Given moderate complexity (6 params) and no output schema, the description explains the input well. However, it does not mention whether this tool requires an editing transaction (sibling tools include transaction management), nor does it describe the return value or confirmation of success. This is a notable gap.

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 description coverage is 0%, so the description must add all parameter meaning. It explains all 6 parameters: path, tablix_name, group_name, aggregates (as a list of {row, expression} with 0-based row index), width (default '1in'), and position ('after' or 'before'). This adds significant value beyond the schema.

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 clearly states the tool is a 'column-axis mirror of add_subtotal_row' and precisely describes its function: adding a TablixMember, TablixColumn, and cells. It distinguishes from the sibling tool add_subtotal_row and explains the parameters, making the purpose very clear.

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?

The description includes a prerequisite ('Group must have been added via add_column_group') and explains the 'position' parameter with default behavior. However, it does not provide explicit guidance on when to use this tool versus alternatives like add_static_column, nor does it mention any exclusion scenarios. The mention of add_subtotal_row as a mirror provides some context.

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

add_subtotal_rowA

Append a subtotal row to a row-axis group. aggregates is a list of {column, expression} entries; column matches against the Details row's textbox names (the same names add_tablix_column uses as column_name — NOT field names). expression is the aggregate (e.g. =Sum(Fields!X.Value)). Columns not listed get blank cells. position='footer' (default) appends; 'header' inserts at body row 1 (right after the group-header row). Group must have been added via add_row_group.

ParametersJSON Schema

Name	Required	Default
`path`	Yes
`position`	No	footer
`aggregates`	Yes
`group_name`	Yes
`tablix_name`	Yes

TDQS

A4.2/5.0

Behavior4/5

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

Given no annotations, the description carries the full burden. It details that unlisted columns get blank cells, explains header/footer insertion points, and clarifies the naming convention for columns. It does not mention error handling or side effects, but it is reasonably transparent for a mutation tool.

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

Conciseness5/5

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

The description is well-structured, front-loaded with the main purpose, and every sentence adds value without redundancy. It is concise yet comprehensive, using precise language like 'appends' vs 'inserts' and clarifying naming conventions.

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

Completeness4/5

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

Given the complexity of 5 parameters and no output schema, the description covers the core behavior, prerequisites, and parameter details. It lacks mention of return values or error conditions, but for a subtotal row addition tool within a well-known context (report building), it is sufficiently complete.

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

Parameters3/5

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

The schema has 0% description coverage, so the description must compensate. It thoroughly explains the 'aggregates' parameter (column and expression meaning) and the 'position' parameter. However, it does not describe 'path', 'group_name', or 'tablix_name', leaving their semantics implied. This is adequate but not fully compensatory.

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 clearly states the tool appends a subtotal row to a row-axis group, specifies the aggregates structure, and distinguishes between header and footer positions. It explicitly mentions that the column names match textbox names used by add_tablix_column, not field names, which differentiates it from similar tools like add_subtotal_column.

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?

The description provides a clear prerequisite (group must be added via add_row_group) and explains the position options with their behavioral implications. However, it does not explicitly mention when to use this tool versus alternatives like add_static_row or other add_ tools, which would improve clarity.

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

add_tablix_columnA

Append (or insert) a column into a tablix. column_name is the textbox name placed in the data row's new cell — must be unique report-wide. expression goes inside that textbox's TextRun (typically =Fields!X.Value). For a tablix with >= 2 rows the first row gets header_text (default = column_name) as a literal, middle rows get blank cells, and the last row gets expression. position is 0-indexed; default appends at end. width defaults to 1in. Inserts a matching top-level TablixMember in the column hierarchy at the same index.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`width`	No
`position`	No
`expression`	Yes
`column_name`	Yes
`header_text`	No
`tablix_name`	Yes

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations provided, the description fully handles behavioral disclosure. It reveals that column_name must be unique report-wide, expression goes inside the TextRun, the behavior for rows (first row header, middle blank, last row expression), and that it inserts a TablixMember. This is comprehensive for a mutation tool.

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

Conciseness5/5

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

The description is a single paragraph with multiple sentences, each adding value without redundancy. It is front-loaded with the main action and efficiently covers defaults and behavior.

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

Completeness4/5

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

Given the tool's complexity (7 parameters, no output schema), the description covers most important aspects: row behavior, defaults, hierarchy insertion. It does not mention the return value or side effects on other report elements, but it is fairly complete for the intended use.

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 description coverage is 0%, so the description compensates well. It explains column_name (unique report-wide), expression (placed in textbox), header_text (default = column_name), position (0-indexed, default append), and width (default 1in). It does not explain path or tablix_name, but these are likely understood from context. Overall, it adds significant meaning beyond the schema.

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 clearly states the tool's action: 'Append (or insert) a column into a tablix'. It specifies the verb ('Append'/'insert') and the resource ('column into a tablix'). The description distinguishes it from sibling tools like add_static_column and add_subtotal_column by detailing its behavior with rows and column hierarchy.

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?

The description provides clear usage context: it explains how to use the tool, including defaults for position, width, and header_text. It also describes the behavior for different row types (first, middle, last). However, it does not explicitly mention when not to use this tool or suggest alternatives like add_static_column, which would have improved guidance.

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

add_tablix_filterA

Append a to a tablix. Operator must be one of the RDL 2016 enumeration (Equal, NotEqual, GreaterThan, In, Between, ...). Returns the new filter's index for follow-up calls. Optional field_format wraps the expression as Format(, fmt) to coerce typed fields for string-parameter comparison. The response includes warnings for cross-checked field/parameter type mismatches.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`values`	Yes
`operator`	Yes
`expression`	Yes
`tablix_name`	Yes
`field_format`	No	Optional format string (e.g. 'MMM, yyyy') wrapping the expression as Format(<body>, '<fmt>').

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It discloses that the tool returns the new filter's index for follow-up calls and that the response includes warnings for type mismatches. However, it does not mention whether the tool requires an editing transaction, which is implied by sibling tools.

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

Conciseness5/5

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

The description is two sentences plus two supplementary sentences on field_format and response. It is concise, well-structured, and front-loads the main action. Every sentence adds value without redundancy.

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

Completeness4/5

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

Given the tool's complexity (6 parameters, no output schema), the description covers the main purpose, operator constraints, optional parameter, return value, and response behavior. It does not explain the concept of a filter or the editing transaction context, but for an agent familiar with RDL, it is sufficient. Minor gaps prevent a 5.

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

Parameters3/5

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

Schema description coverage is low (17%), with only field_format described. The description adds meaning by explaining the operator enumeration and the purpose of field_format, but it does not provide details for essential parameters like path, tablix_name, expression, and values beyond what their names imply. The explanation partially compensates but leaves gaps.

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 clearly states the action ('Append a <Filter>') and the target resource ('to a tablix'), distinguishing it from sibling tools that add other elements or perform different operations. The verb 'append' is specific and the resource is well-defined.

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?

The description provides key usage constraints, such as the operator enumeration ('one of the RDL 2016 enumeration') and the optional field_format for type coercion. However, it does not explicitly guide when to use this tool over alternatives like 'list_tablix_filters' or 'set_...' tools, though the purpose is clear.

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

apply_editsA

Atomic batch: open once → apply ops → lint → save once. Opens an internal transaction against path, dispatches each {tool, args} op through the JSON-RPC tools/call path with transaction_id injected, and commits at the end. On any op failure or lint-error at commit, rolls back — disk is byte-identical to its pre-call state. Compare with dry_run_edit (clones to tempfile, never touches the real file): use dry_run_edit to preview a plan, apply_edits to land it. Returns {applied: [{tool, ok, result|error}], verify, committed}.

ParametersJSON Schema

Name	Required	Description	Default
`ops`	Yes	Ordered list of tool calls to apply atomically.
`path`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

Despite no annotations, the description details transactional behavior: opens internal transaction, dispatches ops via JSON-RPC, and rolls back on failure, ensuring disk byte-identical. It also mentions lint-check at commit. Missing permissions but strong for complexity.

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

Conciseness5/5

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

Extremely concise: opens with summary, explains process, compares with sibling, and returns output format—all in few sentences with no fluff.

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

Completeness4/5

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

Given complexity (atomic batch, rollback, no output schema), the description covers process, rollback guarantee, and return format. Lacks details on error handling for missing paths or permissions, but adequate overall.

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 description coverage is 50%; the description adds meaning: explains ops as ordered list dispatched with transaction_id, and path implied as file path. Adds valuable context beyond schema.

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 clearly states the tool's purpose: 'Atomic batch: open once → apply ops → lint → save once.' It specifies the action (apply edits atomically) and the resource (path), and distinguishes from dry_run_edit.

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

Usage Guidelines5/5

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

Explicitly compares with dry_run_edit: 'use dry_run_edit to preview a plan, apply_edits to land it,' providing clear guidance on when to use each tool.

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

backup_reportA

Copy the report to .bak.. Original is untouched. Cheap explicit checkpoint to call before a destructive batch (remove_*, rename_parameter, etc.). Returns the backup path. Set PBIRB_MCP_AUTO_BACKUP=1 to opt into automatic backups before destructive ops (off by default).

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

A4.8/5.0

Behavior4/5

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

Discloses key non-destructive behavior: original untouched, returns backup path, and automatic backup opt-in. Could mention error handling or failure scenarios, but adequate given no annotations.

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

Conciseness5/5

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

Three concise sentences, front-loaded with the core action. Every sentence adds value without redundancy.

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?

Complete for a simple backup tool: explains action, usage context, return value, and configuration. No gaps given the simplicity and lacking output schema.

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?

Adds meaning beyond the input schema: the path parameter is the source for the backup, and the description specifies the backup filename pattern. Schema coverage is 100%, and the description enriches the context.

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 clearly states the action: copying a report to a timestamped .bak file, preserving the original. It distinguishes itself from siblings as a checkpoint before destructive operations like remove_* and rename_parameter.

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

Usage Guidelines5/5

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

Explicitly recommends using this tool before a destructive batch, naming specific sibling patterns. Also mentions the optional automatic backup via environment variable, providing clear usage context.

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

cancel_editing_transactionA

Discard a transaction. The in-memory tree is dropped; the on-disk file is unchanged from when the transaction was started. Returns {transaction_id, path, discarded}.

ParametersJSON Schema

Name	Required	Description	Default
`transaction_id`	Yes

TDQS

A3.8/5.0

Behavior4/5

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

The description discloses that the in-memory tree is dropped and the on-disk file is unchanged, and mentions the return value. No annotations are present, so the description carries full burden. It lacks details on prerequisites like transaction existence, but is transparent about core behavior.

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 description is concise with two sentences, front-loading the action and effect. The return value is listed but could be integrated better. Overall efficient and clear.

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

Completeness4/5

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

Given the tool's simplicity (one param, no output schema, no annotations), the description covers the main behavioral outcome and return fields. It omits error conditions and prerequisites, but is sufficient for a straightforward cancellation tool.

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

Parameters2/5

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

The only parameter, transaction_id, is not described in the description beyond being mentioned in the return value. Schema coverage is 0%, so the description should compensate, but it does not provide any additional semantics or guidance on the parameter.

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 clearly states it discards a transaction, dropping in-memory tree while keeping on-disk file unchanged. It distinguishes from sibling tools like commit_editing_transaction by explicitly noting the on-disk file is unchanged.

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

Usage Guidelines3/5

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

The description explains what the tool does but does not provide explicit guidance on when to use it versus alternatives (e.g., commit_editing_transaction). The usage context is implied by the description of its effects.

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

commit_editing_transactionA

Lint the in-memory tree, save to disk once (atomic .tmp + rename), and deregister. Aborts (saved=False) if lint surfaces any severity='error' issue — the transaction stays OPEN so the caller can fix the offending state and re-commit. Returns {transaction_id, path, saved, verify}.

ParametersJSON Schema

Name	Required	Description	Default
`transaction_id`	Yes

TDQS

A4/5.0

Behavior4/5

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

With no annotations, the description fully discloses behavior: lint check, atomic save, deregistration, and abort condition. Missing details on potential side effects (e.g., other transactions) but sufficient for primary use.

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 description is front-loaded with the main action and structured logically (lint, save, deregister, abort condition, returns). Slightly verbose but every sentence adds value.

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

Completeness4/5

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

Given the tool's complexity (commit with lint validation) and a simple schema (1 parameter, no output schema), the description covers behavior and return fields adequately. Lacks parameter detail but otherwise complete.

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

Parameters2/5

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

Schema coverage is 0% (no parameter descriptions in the description). The sole parameter 'transaction_id' is implied by the tool name but not clarified in the description. Since schema coverage is low, the description should compensate but does not.

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 clearly states the tool's action: linting the in-memory tree, atomic save to disk, and deregistration. It distinguishes itself from siblings like 'apply_edits' and 'cancel_editing_transaction' by detailing the commit-and-validate process.

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 describes when to use (to commit after edits) and the abort condition with a 'saved=False' return, indicating the caller should fix and retry. Does not explicitly compare to alternatives but context is clear.

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

convert_to_matrixA

Convert a row-grouped + column-grouped tablix into a matrix by dropping the residual Details row group and its body row. Pre-conditions (all checked): the named row_group and column_group must already exist (call add_row_group + add_column_group first); a must still be present in the row hierarchy. Refuses on second call (already a matrix). Use this after the standard insert_tablix_from_template + add_row_group + add_column_group flow to make the leaf the row group instead of Details — without this, cells render at detail granularity. Pair with set_tablix_corner (v0.4 commit 18) to author the top-left label.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`row_group`	Yes
`tablix_name`	Yes
`column_group`	Yes

TDQS

A4/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. Discloses the transformation action, pre-condition checking, and refusal behavior. Missing details on error messages, idempotency, and permission requirements, but core behavioral traits are covered.

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 action, then pre-conditions and use-case. Sentences are information-dense without fluff. Could be slightly trimmed but remains efficient.

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

Completeness2/5

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

Despite complexity, no output schema exists and description does not mention return value, error handling, or side effects beyond the stated transformation. Leaves agent guessing about success/failure signals.

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

Parameters2/5

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

Schema has 4 required params with 0% coverage. Description only implies row_group and column_group are the named groups but adds no format, constraints, or details about path and tablix_name. Fails to compensate for missing schema descriptions.

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?

Clearly states the verb 'convert', resource 'tablix', and outcome 'into a matrix by dropping residual Details row group'. Distinguishes from siblings by referencing the workflow sequence and pairing with set_tablix_corner.

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

Usage Guidelines5/5

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

Explicitly lists pre-conditions (row_group/column_group existence, Details group presence), states refusal on second call, and provides the recommended workflow order. Clearly tells when to use and when not.

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

count_whereA

Emit =Sum(IIf(, 1, 0)) — the SSRS conditional-count idiom. condition is an RDL expression body (no leading '='). Returns a complete top-level expression suitable for set_textbox_value or any RDL sink.

ParametersJSON Schema

Name	Required	Description	Default
`condition`	Yes	RDL expression body, e.g. 'Fields!Status.Value = "Active"'.

TDQS

A4.3/5.0

Behavior3/5

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

No annotations provided; description discloses that the tool emits an expression (pure function) and defines condition format. Lacks details on side effects or safety, but the nature of expression building is inherently non-destructive.

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

Conciseness5/5

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

Two sentences that are front-loaded with the core expression, no extraneous information. Every sentence serves a purpose.

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?

Given a single parameter, no output schema, and low complexity, the description covers the tool's behavior, input format, and output usage comprehensively. No gaps identified.

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 covers 100% of parameter, but description adds critical constraint: condition must be an RDL expression body without leading '='. This adds value beyond the schema's example.

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?

Clearly states it emits a conditional-count idiom using Sum(IIf(...)), and identifies its use case for set_textbox_value or RDL Value sinks. Differentiates from sibling sum_where by specifying it counts (using 1 and 0).

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 describes the output's suitability for set_textbox_value or RDL Value sinks, implying when to use. Does not include explicit when-not-to-use or alternatives, but context with sibling sum_where provides implicit guidance.

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

create_reportA

Emit a minimal valid RDL from scratch at path. Refuses if path exists (no clobbering). Default page_setup is US Letter portrait with 1in margins; pass any subset of {page_height, page_width, margin_top, margin_bottom, margin_left, margin_right, body_width, body_height} to override. datasource is a forward-compat hook — pass {name, workspace_url, dataset_name, provider, integrated_security} to wire a real PBI XMLA endpoint (v0.4 commit 14); omit for a placeholder DataSource1 + DataSet1 stub the caller fills in via subsequent tools. Validates structurally + against the bundled XSD before saving (atomic .tmp + rename). Returns {path, validated, size_bytes}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`datasource`	No
`page_setup`	No

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations, the description fully discloses key behaviors: no clobbering, default page_setup, atomic save with .tmp and rename, structural and XSD validation, and the return value. It could mention error handling for invalid input, but current detail is strong.

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 description is front-loaded with the core action and provides important details in a logical order. While slightly long, it avoids unnecessary words and earns each sentence with specific information like defaults and validation.

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

Completeness4/5

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

Given no output schema, the description includes the return fields. It covers creation from scratch, default values, and validation. It could mention what happens if validation fails, but overall it provides sufficient context for the tool's role alongside siblings.

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 0%, so description compensates well. It explains path as the output location, datasource as a forward-compat hook with wiring details, and page_setup as an override for defaults. This adds meaningful context beyond the schema's type-only definitions.

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 clearly states the tool creates a new RDL report from scratch at a given path, with the phrase 'Emit a minimal valid RDL from scratch'. This distinguishes it from siblings that modify existing reports, as the sibling list includes many tools for adding elements to reports.

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?

The description implies usage scenarios: use this to start a new report, as it refuses if the path exists (no clobbering). It also explains when to provide datasource and page_setup overrides. However, it does not explicitly state when not to use it or compare to alternatives like raw_xml_replace or duplicate_report.

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

describe_reportA

Top-level inventory of an RDL: data sources, datasets, parameters, tablixes, charts, and page setup. Always the first call when planning edits. v0.4: tablixes returns rich shape hints [{name, rows, columns, has_groups, has_subtotals, has_spans}] (was bare strings — migrate with [t['name'] for t in tablixes]). charts (new in v0.4) is a top-level array of chart names.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

A4.3/5.0

Behavior4/5

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

No annotations provided, so the description carries full burden. It describes the output inventory and version changes, but does not explicitly state that it is read-only with no side effects. However, the name and context imply a safe read operation.

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 description is reasonably concise, front-loaded with purpose, and includes necessary version details. It could be slightly tighter but remains informative without excess.

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

Completeness4/5

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

Given no output schema, the description compensates by listing the components returned and noting version-specific changes. It provides sufficient context for an inventory tool, though exact structure details are lacking.

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

Parameters3/5

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

Only one parameter 'path' with 100% schema coverage. The description does not add additional meaning beyond the schema's 'Absolute path to the .rdl file to read'. Baseline score of 3 is appropriate.

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 clearly states it provides a top-level inventory of an RDL, listing specific components (data sources, datasets, parameters, tablixes, charts, page setup), and it distinguishes itself from sibling tools by stating 'Always the first call when planning edits', implying it's an overview tool unlike specific getters.

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

Usage Guidelines5/5

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

Explicitly says 'Always the first call when planning edits', providing clear guidance on when to use this tool. Also includes version-specific migration notes, further aiding usage.

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

dry_run_editA

Apply a list of {tool, args} ops to a tempfile clone of the report; return the unified diff and a verify (validate + lint) report. The original file is NEVER modified. The harness auto-injects path into each op's args, so callers don't supply it. On op failure, dispatch stops; partial diff + verify are still returned. Use this to preview risky multi-step edits before committing.

ParametersJSON Schema

Name	Required	Description	Default
`ops`	Yes	Sequence of tool calls to dispatch against the tempfile.
`path`	Yes

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations, the description fully discloses key behaviors: cloning to tempfile, never modifying original, auto-injecting path, stopping on op failure with partial results. No contradictions.

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

Conciseness5/5

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

Three concise sentences, each providing essential information without redundancy. The first sentence states the core function, the second adds behavioral details, and the third gives usage context.

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?

Given the tool's complexity (previewing multi-step edits), the description covers all critical aspects: operation, behavior on failure, return values, and purpose. No output schema exists, but the description adequately describes outputs.

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?

The description adds value beyond the schema by explaining that the harness auto-injects the path parameter into each op's args, which is not evident from the schema alone. It also clarifies the structure of ops as {tool, args}.

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 clearly states the verb ('Apply'), resource ('list of {tool, args} ops to a tempfile clone'), and deliverables ('unified diff and verify report'). It distinguishes from siblings like apply_edits by emphasizing the dry-run nature.

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?

The description explicitly advises using this tool to 'preview risky multi-step edits before committing,' providing clear when-to-use guidance. While it doesn't explicitly state when not to use, the context with sibling apply_edits implies distinction.

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

duplicate_reportA

Clone an .rdl to a new path. When regenerate_ids=true (default), every rd:DataSourceID and any rd:ReportID is rewritten to a fresh uuid4() so Power BI Report Builder doesn't refuse to load the duplicate due to identity collision. Atomic-write convention from RDLDocument.save_as. Refuses if dst_path already exists. Returns {src, dst, regenerated_ids: list[str]}.

ParametersJSON Schema

Name	Required	Description	Default
`dst_path`	Yes
`src_path`	Yes
`regenerate_ids`	No

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations provided, the description fully discloses the tool's behavior: cloning with ID regeneration, atomic-write, refusal on existing destination, and return value format. This is comprehensive and leaves no ambiguity.

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

Conciseness5/5

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

The description is concise (3 sentences + return type), front-loaded with the primary action. Every sentence adds essential information without redundancy.

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?

The description covers the tool's purpose, default behavior, failure condition, and return value. It even explains the rationale for ID regeneration. This is complete for a complex clone operation.

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?

The description adds significant meaning beyond the schema, explaining the effect of 'regenerate_ids' with specifics about UUID rewriting for DataSourceID and ReportID. It clarifies that 'dst_path' is the new path and implies 'src_path' is the source.

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 uses a specific verb 'clone' and resource '.rdl', clearly distinguishing it from siblings like 'backup_report' or 'create_report'. It explicitly states the action and the file type.

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?

The description explains the default behavior of 'regenerate_ids' and why it is needed (to avoid identity collisions in Power BI Report Builder). It also mentions atomic-write convention and failure condition. While it doesn't explicitly compare to alternatives, the context is clear enough for when to use this tool.

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

find_textbox_by_valueA

Find every Textbox whose text matches a Python regex pattern. Searches Body / PageHeader / PageFooter. A textbox with multiple matching runs surfaces once per match. Returns [{textbox, value, region}]. Useful for finding stale =Parameters!Old.Value references after rename_parameter, or any cross-cutting expression edit.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`pattern`	Yes	Python regex (re.search); not RDL/SQL glob.

TDQS

A4.3/5.0

Behavior4/5

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

Discloses search scope (Body/PageHeader/PageFooter), behavior for multiple matches ('surfaces once per match'), and return format ('[textbox, value, region]'). No annotations present, so description carries full burden.

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

Conciseness5/5

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

Three sentences, front-loaded with core action, no unnecessary words.

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?

Given no output schema, description explains return shape and matching behavior. Sufficient for an AI agent to understand tool purpose and output.

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

Parameters3/5

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

Two parameters: 'path' and 'pattern'. Schema description covers 50% (only pattern described as 'Python regex (re.search)'). Description adds no further info on 'path' or usage meaning beyond the schema.

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?

Description states specific verb 'Find' and resource 'Textbox' with criteria (value matching regex). Distinguishes from sibling 'find_textboxes_by_style' which searches by style.

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?

Provides explicit use case: 'finding stale =Parameters!Old.Value references after rename_parameter' and 'any cross-cutting expression edit'. Implies usage context but does not exclude when not to use or list alternative tools.

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

find_textboxes_by_styleA

Search for textboxes matching one or more style filters. Filters AND together (every supplied filter must match). Returns [{name, location, matched_fields}] where location is best-effort 'body' / 'header' / 'footer' / 'tablix:' / 'rectangle:'. Returns [] when no filters supplied. Pair with set_textbox_style_bulk for discovery+apply patterns (e.g. 'recolor every red textbox').

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`color`	No
`format`	No
`font_size`	No
`font_style`	No
`text_align`	No
`font_family`	No
`font_weight`	No
`padding_top`	No
`border_color`	No
`border_style`	No
`border_width`	No
`padding_left`	No
`writing_mode`	No
`padding_right`	No
`padding_bottom`	No
`vertical_align`	No
`text_decoration`	No
`background_color`	No

TDQS

A4/5.0

Behavior4/5

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

Describes return format with name, location, matched_fields and location best-effort places. States returns [] when no filters supplied. No contradictions. With no annotations, description carries full burden and does well.

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

Conciseness5/5

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

Three concise sentences with front-loaded purpose, logic, return format, and pairing suggestion. No redundant information.

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

Completeness3/5

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

Covers return format and empty case, but given 19 parameters and no output schema, lacks details on value formats, case sensitivity, or exact match semantics. Adequate but could use examples.

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

Parameters2/5

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

Schema description coverage is 0%. Description only mentions 'style filters' but does not explain any parameter values or formats. Parameter names are somewhat self-explanatory, but lack of examples or accepted values hurts usability.

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?

Clear verb 'Search for' and resource 'textboxes' with 'style filters'. Distinguishes from sibling find_textbox_by_value by focusing on style rather than value. The AND logic is explicitly stated.

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 mentions AND filtering and pair with set_textbox_style_bulk for discovery+apply patterns. Provides example. Does not explicitly state when not to use, but context implies alternative sibling tool for value search.

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

get_chartA

Return effective state of a named Chart: position, size, dataset, palette, series list (name/type/subtype/value expression/color), category groups (name/expression/label), axes (category and value), legend, title, Style, Visibility. Symmetric with get_textbox / get_image / get_rectangle.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes

TDQS

A3.5/5.0

Behavior3/5

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

Describes returned properties (position, size, etc.) and states 'return effective state', implying a read operation. No annotations exist, so description carries full burden. Missing details on side effects, auth, or rate limits, making it moderately transparent.

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?

Single sentence listing many output fields; no wasted words. Efficient but slightly dense. Could benefit from minimal structuring (e.g., bullet points), but overall concise.

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

Completeness3/5

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

Lists output fields in detail, partially compensating for lack of output schema. However, it ignores parameter documentation entirely. Given two required parameters and no schema descriptions, more completeness is needed.

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

Parameters2/5

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

Schema coverage is 0% and description does not explain the two required parameters ('name' and 'path'). Only mentions 'named Chart' which hints at 'name', but no elaboration on 'path' or parameter semantics. Fails to compensate for missing schema descriptions.

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?

Clearly states it returns the effective state of a named Chart with a detailed list of components. The reference to symmetry with get_textbox/get_image/get_rectangle distinguishes it from sibling tools for other item types.

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

Usage Guidelines3/5

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

Implied usage for obtaining chart state, but no explicit when-to-use or alternatives. The symmetry note provides some context but lacks guidance on when not to use it or prerequisites.

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

get_datasetB

Single-DataSet read-back (parity with get_textbox / get_image / get_rectangle / get_chart / get_data_source). Returns dataset name, data_source, command_text, fields (with both data_field and value), query_parameters, filters, and designer_state_present.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes

TDQS

B3.1/5.0

Behavior2/5

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

No annotations are provided, and the description only lists return fields. It does not disclose side effects, authentication requirements, rate limits, or destructive actions. The read-only nature is implied but not explicit.

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 description is a single, clear sentence that front-loads the purpose. However, the parenthetical list of fields is somewhat lengthy and could be streamlined.

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

Completeness3/5

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

Given no output schema, the description adequately lists the returned fields. However, it fails to explain the parameters or provide behavioral context, leaving gaps in completeness for an agent to properly invoke the tool.

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

Parameters1/5

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

The schema has two required parameters ('path' and 'name') with zero description coverage. The description adds no meaning beyond the schema, leaving the agent to guess the purpose and format of these parameters.

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 clearly states it is a 'Single-DataSet read-back' tool, specifies the verb 'get' and resource 'dataset', and distinguishes from sibling tools like get_datasets, get_textbox, and get_image by noting parity and singular scope.

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

Usage Guidelines3/5

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

The description implies usage for retrieving a single dataset but does not explicitly state when to use this over alternatives like get_datasets (plural) or other get tools. It lacks 'when to use' and 'when not to use' guidance.

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

get_datasetsB

Full DAX command text, fields, query parameters, and dataset-level filters for every DataSet in the report.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

B3.2/5.0

Behavior2/5

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

The description discloses what data is returned (DAX command text, fields, query parameters, filters) but does not mention if the operation is read-only, side effects, error handling, or required permissions. Without annotations, the description carries the full burden for behavioral context, and it falls short.

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 description is a single sentence that concisely lists the returned data. It is front-loaded with purpose and avoids unnecessary words. However, it could be slightly more structured with bullet points for readability.

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

Completeness3/5

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

Given the tool's simplicity (one parameter, no output schema, no annotations), the description provides a reasonable overview of what it does. However, it lacks details on the return format, error behavior, or performance implications, which would be helpful for a complete understanding.

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

Parameters3/5

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

The input schema has 100% coverage with one parameter ('path') described as 'Absolute path to the .rdl file to read.' The description does not add extra meaning beyond the schema, but the baseline score of 3 is appropriate since the schema already fully documents the parameter.

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 clearly states that the tool returns 'Full DAX command text, fields, query parameters, and dataset-level filters for every DataSet in the report.' It uses a specific verb ('get') and resource ('datasets'), and it is well-distinguished from its sibling 'get_dataset' which implies a single dataset.

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

Usage Guidelines2/5

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

The description does not provide any guidance on when to use this tool instead of alternatives like 'get_dataset' (which likely retrieves a single dataset) or other dataset-related tools. No prerequisites, limitations, or usage context are mentioned.

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

get_data_sourceA

Single-DataSource read-back (parity with get_textbox / get_image / get_rectangle / get_chart). Returns the same shape as one entry of list_data_sources.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes

TDQS

A3.8/5.0

Behavior3/5

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

With no annotations, the description must fully disclose behavior. It indicates the tool is a read operation and describes the output shape. However, it omits error conditions (e.g., data source not found), authentication needs, or any side effects, leaving gaps in transparency.

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

Conciseness5/5

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

The description is two sentences with no wasted words. The first sentence states the core purpose, and the second describes the output. It is front-loaded and efficient.

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

Completeness3/5

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

The tool is a simple getter, but the description lacks parameter details and error behavior. While it provides output shape and comparison to siblings, it does not fully compensate for missing schema descriptions or output schema, leaving some ambiguity for the agent.

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

Parameters2/5

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

The input schema has two parameters (name, path) with no descriptions (0% coverage). The description does not explain what these parameters represent or how to use them, adding minimal value. For a tool with two undocumented parameters, this is insufficient.

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 clearly states it is a 'Single-DataSource read-back' and explicitly compares to similar getter tools, distinguishing its purpose. It also specifies the output shape, making it easy to understand what the tool does.

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?

The description implies usage by comparison to similar getters ('parity with get_textbox / get_image / get_rectangle / get_chart') and contrasts with list_data_sources by noting it returns a single entry. However, it does not explicitly state when to use or avoid this tool versus alternatives, missing a clear when-not.

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

get_embedded_image_dataA

Read an embedded image's base64 for porting it to another report without re-reading from disk. Returns {name, mime_type, base64, byte_size}. base64 is the raw text of the ImageData element; byte_size is the decoded size for sanity-checking. Refuses with ElementNotFoundError if the named entry isn't in .

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It discloses the tool is a read operation ('Read an embedded image'), describes the error condition ('Refuses with ElementNotFoundError'), and explains the return fields. It does not mention permissions or rate limits, but for a safe read tool this is acceptable.

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

Conciseness5/5

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

The description is two sentences, front-loaded with purpose, then return format, then error behavior. Every sentence adds value with no redundancy. Highly efficient.

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

Completeness4/5

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

For a 2-parameter tool with no output schema, the description covers the return object, error case, and use case. It could explicitly state that 'path' refers to the report file path, but otherwise it is sufficiently complete for an agent to understand the tool's behavior.

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

Parameters2/5

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

Schema coverage is 0% with no descriptions for 'path' and 'name'. The description clarifies that 'name' refers to the image entry in <EmbeddedImages>, but 'path' is not described at all. This leaves the agent guessing about the path parameter. The description does not fully compensate for the lack of schema descriptions.

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 clearly states the tool reads an embedded image's base64 data for porting to another report. It specifies the return object and distinguishes from sibling tools like list_embedded_images (which only lists) and get_image (likely returns different format). The purpose is specific and actionable.

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?

The description explicitly says when to use: for porting an image without re-reading from disk. It provides context but does not state when not to use or explicitly mention alternatives. However, the context is clear enough for an agent to infer appropriate usage.

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

get_expression_referenceA

Return a static cheat-sheet of common RDL expression patterns: globals, parameters, fields, aggregates, conditionals, strings, dates. Each entry is {name, syntax, example, description}. Call this when authoring a textbox value or filter expression instead of guessing — and note the explicit encoding hint for the & concat operator.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.7/5.0

Behavior4/5

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

Without annotations, the description carries full burden. It discloses the tool returns a static cheat-sheet (read-only, no side effects), and specifies the output structure. It also mentions a specific encoding hint. However, it omits potential details like whether the content can change or any access limitations, though for a simple reference tool this is acceptable.

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

Conciseness5/5

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

The description is two sentences: first states what it returns, second gives usage advice and a specific hint. Both sentences are essential and front-loaded. No fluff.

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?

The tool has no parameters and no output schema. The description fully explains what it returns (categories and structure) and when to use it (textbox/filter expression authoring). It also includes a practical encoding hint. This is complete for its complexity.

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?

There are zero parameters, so baseline is 4. The description adds no parameter info (none needed), but it adds value by describing the content and usage context, which is appropriate.

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 clearly states the tool returns a static cheat-sheet of common RDL expression patterns, listing categories (globals, parameters, fields, etc.) and the structure of each entry (name, syntax, example, description). It distinguishes itself from sibling tools, which are all about editing report components, not providing reference.

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

Usage Guidelines5/5

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

The description explicitly says 'Call this when authoring a textbox value or filter expression instead of guessing', providing clear when-to-use guidance. It also notes an encoding hint for the `&` concat operator, adding practical usage detail.

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

get_imageB

Return effective state of a named Image: position, size, Source (External / Embedded / Database), Value, Sizing (AutoSize / Fit / FitProportional / Clip), MIMEType, Style, Visibility.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes

TDQS

B3.2/5.0

Behavior3/5

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

With no annotations, the description carries the full burden. It states the tool returns state, implying read-only behavior, but does not disclose prerequisites (e.g., image existence), side effects, or other constraints. It provides minimal behavioral context.

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 description is a single concise sentence listing return fields, front-loaded with the main purpose. It could be improved by structuring parameters separately, but it is short and to the point.

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

Completeness2/5

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

The description covers only return values. Without output schema, annotations, or parameter explanation, it is incomplete for a simple getter tool. It lacks critical information about inputs and usage context.

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

Parameters1/5

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

The description does not mention the required parameters 'name' and 'path'. Given 0% schema description coverage, the description must compensate, but it only describes return fields, leaving parameter meaning entirely undocumented.

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 clearly states 'Return effective state of a named Image' with a specific verb and resource, and lists the fields returned (position, size, Source, etc.), distinguishing it from sibling getters like get_chart or get_dataset.

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

Usage Guidelines3/5

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

The description implies usage for retrieving image state, but does not provide explicit guidance on when to use this tool versus siblings like get_embedded_image_data or set_image_* tools. No when-not or alternative guidance is given.

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

get_parametersC

Report parameter declarations: name, data type, prompt, flags.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states what is reported, but fails to mention traits like read-only nature, error handling for invalid paths, or whether the tool requires an existing report. This is inadequate for a tool with no annotation support.

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 description is concise at one sentence, front-loading the core purpose. However, it may be too brief to provide sufficient context, but it avoids unnecessary detail.

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

Completeness3/5

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

Given the simplicity of the tool (one parameter, no output schema), the description is adequate but not complete. It does not explain the return format or confirm that multiple parameters can be retrieved. For a straightforward getter, a description with slightly more detail would be expected.

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

Parameters3/5

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

The input schema has 100% coverage for the single parameter 'path', which is already described. The description does not add any extra semantic value beyond what the schema provides, so the baseline score of 3 is appropriate.

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

Purpose4/5

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

The description clearly states it reports parameter declarations with specific fields (name, data type, prompt, flags). It uses a verb 'report' and identifies the resource 'parameter declarations', but does not differentiate from sibling get_* tools like get_chart or get_dataset which follow a similar pattern.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives such as describe_report or other get_* tools. There are no explicit when-to-use or when-not-to-use instructions, leaving the agent to infer context solely from the tool name.

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

get_rectangleB

Return effective state of a named Rectangle: position, size, names of contained ReportItems, Style, Visibility.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes

TDQS

B3.4/5.0

Behavior3/5

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

With no annotations, the description carries full responsibility. The verb 'Return' implies a read-only, side-effect-free operation, which is appropriate. However, no additional behavioral traits (e.g., authentication requirements, error conditions) are disclosed. The description is minimally adequate.

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

Conciseness5/5

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

The description is a single sentence of 12 words, efficiently stating purpose and output. It is front-loaded with the key verb and resource, achieving high conciseness without loss of essential information.

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

Completeness3/5

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

While the description lists all returned properties, it does not explain the 'path' parameter. The tool is simple (2 parameters, no output schema), so the missing parameter explanation prevents full completeness. The list of returned properties compensates somewhat, but the gap remains.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must explain parameters. It only mentions 'named Rectangle', implying 'name' identifies the rectangle, but 'path' is not explained. The agent lacks context on what 'path' represents (e.g., location in report hierarchy). This is a significant gap.

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 clearly states the action ('Return effective state'), the resource ('named Rectangle'), and lists the returned properties. It distinguishes get_rectangle from sibling get tools that target different entities (chart, dataset, textbox, etc.).

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, limitations, or when it should not be used. Among sibling get tools, no comparative advice is given.

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

get_tablixesA

Tablix layout with stable IDs: columns, row/column groups, sort expressions, filters, visibility. Required input for any tablix edit.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

A3.6/5.0

Behavior3/5

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

No annotations are provided, so the description must disclose behavior. It implies a read operation but does not explicitly state it is non-destructive or mention error conditions. The output is described, but transparency is limited given the lack of annotations.

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

Conciseness5/5

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

The description is extremely concise: two sentences with no wasted words. It is front-loaded with the main output and ends with usage hint. Every word earns its place.

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

Completeness4/5

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

Given the simplicity (one param, no output schema), the description covers the main purpose and usage context. It could mention that the 'stable IDs' refer to IDs needed for editing, but it is sufficient for an agent to understand the tool's role.

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

Parameters3/5

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

Schema coverage is 100% with one parameter 'path' well described. The description adds no additional meaning beyond 'Tablix layout' context, which is already clear from the tool name and general description. Baseline score of 3 is appropriate.

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

Purpose4/5

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

The description states it returns a 'Tablix layout with stable IDs' detailing columns, groups, etc. It also indicates it is 'Required input for any tablix edit', which distinguishes it from mutation siblings. However, it does not explicitly contrast with other get tools like get_chart, but the resource is specific.

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

Usage Guidelines3/5

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

The description provides context that this tool is needed before editing a tablix, implying usage. However, it does not specify when not to use it or mention alternatives. The guidance is adequate but not comprehensive.

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

get_textboxA

Return effective state of a named Textbox: position, size, Visibility, CanGrow, CanShrink, plus a nested style dict that mirrors set_textbox_style's routing — {box: {BackgroundColor, VerticalAlign, padding, ...}, border: {Style, Color, Width}, paragraph: {TextAlign}, run: {FontFamily, FontSize, FontWeight, Color, Format, ...}}. Empty branches are dropped. runs[] entries each carry their own per-run style. Searches the entire report; tablix-cell textboxes have None for top/left/width/height. Top-level positioned items with a missing or coerce to '0in' (RDL default).

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes

TDQS

A3.8/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It discloses return structure, edge cases (tablix-cell textboxes with None dimensions), coercion behavior ('0in' default), and the fact that empty branches are dropped. It does not mention permissions or side effects, but these are minimal for a read operation.

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 description is a single dense paragraph that front-loads the main purpose and packs detailed behavioral information efficiently. It could be improved with bullet points, but it is concise relative to the information provided.

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

Completeness4/5

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

Given no output schema, the description thoroughly explains the return value structure, including nested style dict and per-run styles, and addresses edge cases. It is sufficient for understanding the output, though error scenarios are not mentioned.

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

Parameters2/5

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

The input schema has two required parameters (name, path) with no descriptions (0% coverage). The description mentions 'named Textbox' but does not explain what 'name' or 'path' represent or their expected format. This leaves ambiguity for the AI agent.

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 clearly states it returns the effective state of a named Textbox, listing specific properties (position, size, Visibility, CanGrow, CanShrink, style dict). It distinguishes from siblings like find_textbox_by_value by focusing on a single named textbox's full state.

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

Usage Guidelines3/5

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

The description implies when to use (to get a textbox's state) but does not explicitly state when not to use or mention alternative tools. It provides context (searches entire report) but lacks explicit guidelines.

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

iif_formatA

Emit =IIf(, , ). All three args are expression bodies (no leading '='); string literals must already be quoted, e.g. true_value='"Yes"'.

ParametersJSON Schema

Name	Required	Description	Default
`condition`	Yes
`true_value`	Yes
`false_value`	Yes

TDQS

A4.2/5.0

Behavior4/5

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

The description discloses that arguments are expression bodies (no leading '=') and that string literals must be pre-quoted, providing important behavioral context beyond the basic schema.

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

Conciseness5/5

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

The description is extremely concise with two focused sentences that convey the essential syntax and constraints without any extraneous information.

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

Completeness4/5

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

The tool is simple with no output schema, and the description covers the key usage rules; it could mention the expected return value type, but overall it is fairly complete for its purpose.

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?

With 0% schema coverage, the description compensates by explaining the nature of the three parameters as expression bodies and providing a quoting example, adding significant meaning beyond mere type strings.

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 explicitly states it emits an IIf expression with a specific syntax, clearly distinguishing it from sibling tools that add or set report elements.

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

Usage Guidelines3/5

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

There is no explicit guidance on when to use this tool versus alternatives, but the description implies it is for generating IIf expressions in contexts where expression bodies are required.

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

insert_chart_from_templateA

Build and append a basic Column chart to /. Single category axis grouped by category_field; single Y series Sum(Fields!.Value). dataset_name must already exist. Change post-insert (e.g. to Bar / Line / Pie) by editing the chart directly.

ParametersJSON Schema

Name	Required	Description	Default
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes
`width`	Yes
`height`	Yes
`value_field`	Yes
`dataset_name`	Yes
`category_field`	Yes

TDQS

A3.8/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses that the chart is appended, uses Sum aggregation, and can be modified post-insert. However, it does not mention error behavior, idempotency, or side effects (e.g., overwriting). The description is adequate but not thorough.

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

Conciseness5/5

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

Two sentences that are front-loaded and concise. Every sentence adds value: purpose, structure, and a tip for post-insert modification. No wasted words.

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

Completeness3/5

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

Given 9 required parameters, no output schema, and no annotations, the description covers the core behavior but lacks details on parameter semantics and return values. It partially differentiates from siblings but is not fully complete for confident tool selection.

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

Parameters2/5

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

Schema coverage is 0%, so the description must compensate. Only 3 of 9 parameters (dataset_name, category_field, value_field) are described. Parameters like top, left, path, name, width, height are not explained, leaving significant ambiguity for the agent.

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 clearly states it builds and appends a basic Column chart to <Body>/<ReportItems>, specifying the chart structure (single category axis grouped by category_field, single Y series with Sum aggregation). It is distinct from siblings like add_chart_series or set_chart_series_type, which modify existing charts.

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?

Provides clear context: the chart is a Column chart by default, dataset_name must exist, and type can be changed post-insert. However, it does not explicitly state when not to use this tool vs. alternatives like add_chart_series or set_chart_series_type.

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

insert_tablix_from_templateA

Build and append a basic Tablix to /. One column per name in columns; header row gets the column name as a static label, detail row binds to =Fields!.Value. dataset_name must already exist. width is the tablix outer width — each column defaults to 1in regardless, so for a 3-column tablix the columns sum to 3in even if you pass width=10cm. Resize columns afterwards via direct edits or future column-width tools.

ParametersJSON Schema

Name	Required	Description	Default
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes
`width`	Yes
`height`	Yes
`columns`	Yes
`dataset_name`	Yes

TDQS

A3.8/5.0

Behavior4/5

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

No annotations present, so description bears full responsibility. It discloses the append behavior, dataset requirement, width behavior (columns default to 1in regardless of width), and need for post-hoc column resizing. It does not mention destructive potential, but appending is non-destructive. Overall, it provides good behavioral insight beyond the basic action.

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?

Description is concise at ~70 words, front-loading the main purpose. It uses clear examples and straightforward language. Minor improvement could be structuring into bullet points or separate sentences for readability, but current form is acceptable without wasted words.

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

Completeness3/5

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

Given 8 required parameters and no output schema, the description covers the critical aspects (columns, dataset_name, width) but omits explanation of `path`, `top`, `left`, `height`, and `name`. It also does not clarify the return value or side effects. It is adequate for simple scenarios but leaves gaps for new users.

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

Parameters3/5

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

Schema coverage is 0%, so description must compensate. It explains `columns` (list of column names), `dataset_name` (must exist), and `width` (outer width, columns not scaled). However, it does not describe `top`, `left`, `height`, `path`, or `name`. It adds significant meaning for some params but leaves others unclear.

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?

Description clearly states the tool builds and appends a basic Tablix to <Body>/<ReportItems> with header and detail rows. It explains the column structure (static labels, Field! bindings) and distinguishes from column-width tools, though not explicitly from siblings. The verb 'Build and append' is specific and the resource is clear.

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

Usage Guidelines3/5

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

Description mentions prerequisite that dataset_name must exist and hints at column-width tools for resizing, but does not explicitly state when to use this tool versus alternatives like add_tablix_column or other add_* tools. No 'when not to use' guidance is provided.

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

lint_reportA

Run static-analysis lint rules against an .rdl. Sixteen rules cover the v0.2/v0.3 sweep bug classes (multi-value-eq, missing-field-reference, dangling-embedded-image, pbidataset-at-prefix, parameter-layout-out-of-sync, double-encoded-entities, stale-designer-state, tablix-span-misplaced, dataset-fields-out-of-sync, etc.). Returns {issues, rules_run} with each issue {severity, rule, location, message, suggestion?}. Optional rules selects a subset by name.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`rules`	No	Optional subset of rule names; default runs all 16.

TDQS

A4.3/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full burden. It describes the return format {issues, rules_run} with issue fields, and mentions the optional rules parameter. It does not explicitly state read-only, but 'lint' implies non-destructive analysis.

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 description is concise, front-loaded with the main action, and efficiently lists the rules in a parenthetical. It could be more structured but is clear and without waste.

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

Completeness4/5

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

Given no output schema, the description adequately covers return format, parameters, and rule list. It lacks mention of error conditions or performance, but for a lint tool the provided info is sufficient for an AI to invoke it correctly.

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 50% (only rules has description). The description adds meaning by explaining that path refers to an .rdl file and that rules selects a subset. It also lists the specific rule names, adding value beyond schema.

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 explicitly states 'Run static-analysis lint rules against an .rdl', providing a specific verb and resource. It enumerates the rule categories, distinguishing itself from sibling tools which are all add/set/get operations.

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?

The description clearly explains what the tool does and the optional rules parameter, but does not explicitly state when to use it versus alternatives. Since no sibling tool performs linting, the context is still clear.

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

list_body_itemsA

List every named ReportItem at the top level of . Returns name, type (Tablix / Textbox / Image / Rectangle / Subreport / Chart / etc.), top, left, width, height. Use before set_body_item_position / set_body_item_size when you don't already know what's in the body.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

A4.5/5.0

Behavior4/5

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

Despite no annotations, description clearly indicates a read-only listing operation with no side effects. It could mention behavior for empty body or invalid paths, but it is transparent enough for a simple listing tool.

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

Conciseness5/5

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

Two sentences, no fluff, front-loaded with purpose. Each sentence adds value: first lists output, second provides usage guidance.

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?

Given no output schema, description adequately explains return fields. For a simple tool with one parameter, it covers essential context without missing critical information.

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

Parameters3/5

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

Schema coverage is 100% with a single 'path' parameter documented as 'Absolute path to the .rdl file to read.' Description adds no additional meaning beyond the schema, meeting baseline expectation.

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?

Description specifies verb 'list', resource 'ReportItem at the top level of <Body>', and what is returned (name, type, dimensions). It clearly distinguishes from sibling tools by mentioning usage before set_body_item_position/set_body_item_size.

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

Usage Guidelines5/5

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

Explicitly states when to use: 'before set_body_item_position / set_body_item_size when you don't already know what's in the body.' This provides clear context and alternative tools.

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

list_dataset_filtersA

List dataset-level filters in document order. Returns [{expression, operator, values}]; index in the list is the stable handle for remove_dataset_filter. DataSet filters apply to every consumer of the dataset (every Tablix / Chart bound to it); use list_tablix_filters for per-tablix filtering.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`dataset_name`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, the description provides good behavioral context: it returns a list with structure, indices are stable handles for removal, and it explains the scope. It implicitly assumes read-only, but could explicitly state no side effects.

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

Conciseness5/5

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

The description is extremely concise with two sentences. The first states the core purpose, and the second adds context and alternatives without any wasted words.

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?

Given the tool's simplicity and lack of output schema, the description adequately explains the return format, the use of the index as a handle, and the relationship to other tools. It covers all necessary information for an agent to use the tool correctly.

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

Parameters2/5

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

Schema description coverage is 0%, and the description does not elaborate on the parameters 'path' and 'dataset_name'. The parameter names are somewhat clear, but the description adds no additional meaning or constraints beyond the schema.

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 clearly states the action (List), the resource (dataset-level filters), and specifies the return format and the significance of the index. It also distinguishes from sibling tools like list_tablix_filters.

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

Usage Guidelines5/5

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

The description explicitly explains when to use this tool versus list_tablix_filters by clarifying that dataset filters apply to every consumer, while per-tablix filtering uses the alternative.

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

list_data_sourcesA

Return a rich list of every in the report — name, data_provider, connect_string, integrated_security, shared_reference, security_type, data_source_id. describe_report.data_sources returns names only; this tool is the authoring-friendly read.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

A4/5.0

Behavior3/5

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

No annotations were provided, so the description must fully disclose behavior. It states this is a read operation ('authoring-friendly read') and lists the fields returned, which is adequate for a non-destructive tool. However, it does not address potential side effects, authentication requirements, or error handling, which are minor omissions.

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

Conciseness5/5

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

The description is concise at two sentences, with the core purpose front-loaded. Every sentence adds value: the first states the output, the second distinguishes it from a sibling tool. No filler or redundant information.

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

Completeness4/5

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

Despite lacking an output schema, the description lists all fields returned, making the return value clear. It also references a sibling tool for comparison. It does not explain edge cases (e.g., invalid path, empty report), but for a simple read tool this is acceptable.

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

Parameters3/5

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

The schema has 100% coverage for the single parameter 'path', which is well described in the schema itself. The tool description does not add additional information about the parameter beyond what the schema already provides, so the baseline score of 3 is appropriate.

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 clearly states the tool returns a 'rich list' of DataSources with specific fields, and explicitly distinguishes itself from 'describe_report.data_sources' which returns only names. The verb 'Return' and the resource 'rich list of every <DataSource>' make the purpose unambiguous.

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?

The description provides explicit guidance on when to use this tool versus the alternative 'describe_report.data_sources' (rich list vs names only). It does not explicitly state when not to use it, but the context is clear that it's for authoring-friendly reads, implying it's not for modifications.

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

list_embedded_imagesB

List embedded images in the report by name and MIME type. Returns an empty list when is absent.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

TDQS

B3/5.0

Behavior3/5

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

Discloses empty list behavior when <EmbeddedImages> is absent, but does not cover permissions, side effects, or sorting. No annotations to supplement.

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?

Two sentences with no filler, front-loaded with core action. Could be slightly improved without becoming verbose.

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

Completeness2/5

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

Given no output schema, no annotations, and an undocumented parameter, the description is insufficient. It explains return value for empty case but fails to define the input parameter.

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

Parameters1/5

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

The sole parameter 'path' is undocumented in both schema and description. The description provides no explanation of what path refers to, leaving the agent uninformed.

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?

Clearly states the tool lists embedded images by name and MIME type, includes behavior for missing element, and is distinct from sibling tools like add_embedded_image and get_embedded_image_data.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives such as get_embedded_image_data for data retrieval or add_embedded_image for additions.

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

list_footer_itemsC

Same shape as list_body_items but for .

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

C2.5/5.0

Behavior2/5

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

No annotations are provided, so the description must stand alone. It does not disclose whether the tool is read-only, destructive, or any side effects. The brief statement offers no behavioral context.

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

Conciseness3/5

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

The description is very short (one sentence) but front-loaded. However, it could be more direct by stating 'Lists footer items' instead of relying on a reference.

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

Completeness2/5

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

Given no output schema and many sibling tools, the description minimally explains what the tool does. It does not elaborate on return format or scope, leaving gaps for an AI agent.

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

Parameters3/5

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

Schema coverage is 100% for the single 'path' parameter, which is already described in the input schema. The description adds no additional meaning beyond the schema.

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

Purpose3/5

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

The description 'Same shape as list_body_items' implies listing items, but it doesn't independently state the verb+resource. It relies on sibling context, making it somewhat clear but not self-contained.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives like list_header_items or list_body_items. No prerequisites or restrictions are mentioned.

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

list_header_itemsC

Same shape as list_body_items but for .

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

C2.2/5.0

Behavior1/5

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

No annotations provided, and the description fails to disclose any behavioral traits such as read-only nature, side effects, or required permissions. The agent gets no insight into what happens when the tool is invoked.

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

Conciseness2/5

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

The description is extremely short but achieves conciseness at the expense of informativeness. It fails to earn its place by providing useful details, resulting in under-specification.

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

Completeness2/5

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

As a list tool without an output schema, the description should explain what the tool returns. It does not, and it relies on knowledge of list_body_items, making it incomplete for standalone use.

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

Parameters3/5

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

The input schema covers 100% of parameters with a description for 'path'. The tool description adds no additional meaning beyond the schema, so baseline score of 3 applies.

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

Purpose3/5

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

The description vaguely indicates the tool operates on PageHeader by referencing list_body_items, but does not explicitly state the action (e.g., 'list items'). This makes the purpose unclear without prior knowledge of the sibling tool.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. The description only mentions similarity to list_body_items without differentiating use cases or exclusions.

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

list_tablix_filtersA

List all filters on a named tablix in document order. Returns expression, operator, and values per filter; index in the list is the stable handle for remove_tablix_filter.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`tablix_name`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

Without annotations, the description carries the full burden. It discloses the non-destructive nature (listing), the returned fields, and the stable handle property. It does not discuss edge cases or permissions, but for a simple list operation, it is sufficiently transparent.

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

Conciseness5/5

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

The description is a single sentence that efficiently conveys the action, output, and a key integration point. No unnecessary words.

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

Completeness4/5

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

Given the absence of an output schema, the description adequately explains the return (expression, operator, values) and the stable handle. It provides enough context for downstream usage with remove_tablix_filter. However, it lacks details on the output format.

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

Parameters2/5

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

Schema coverage is 0%, so the description should compensate. It does not explain what 'path' and 'tablix_name' represent, leaving the agent to infer from context. The description focuses on output rather than input parameters, which is a gap.

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 clearly states 'List all filters on a named tablix in document order' with a specific verb and resource. It distinguishes from siblings like add_tablix_filter and remove_tablix_filter by mentioning the stable handle for removal.

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?

The description implicitly guides usage by linking the returned index to remove_tablix_filter, indicating a common workflow. However, it does not explicitly state when to use this tool versus alternatives or when not to use it.

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

raw_xml_replaceA

Replace the single element matched by xpath with new content. content is parsed with RDL as the default namespace and 'rd:' bound, so bare names like x work without explicit xmlns. Refuses on zero matches, multiple matches, or if the xpath targets the root. Saves atomically. Returns {xpath, kind, changed}.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`xpath`	Yes
`content`	Yes	XML for the replacement element. Exactly one top-level element.

TDQS

A4.4/5.0

Behavior5/5

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

No annotations exist, so the description fully discloses behavior: namespace handling, refusal conditions, atomic saves, and return format. This is comprehensive.

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

Conciseness5/5

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

Four sentences, front-loaded with purpose, then key details. No wasted words.

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

Completeness4/5

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

Covers most aspects: purpose, namespace, error conditions, atomicity, return. Lacks mention of transaction requirements (sibling tools show start/commit editing transaction).

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?

Adds meaning for xpath and content parameters (namespace parsing, element constraints). Schema only describes content; description compensates partially but does not explain the path parameter.

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?

Clearly states it replaces an element matched by XPath with new content. Differentiated from sibling tools like raw_xml_view and specific setter tools.

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

Usage Guidelines3/5

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

Describes conditions where it refuses but does not explicitly guide when to use alternatives. The context implies use for direct XML manipulation, but no exclusions or comparisons to other tools.

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

raw_xml_viewA

Read-only XPath query against the report. Returns matched elements as serialised XML strings. XPath context is (the root); 'r:' is bound to the RDL namespace, 'rd:' to the rd namespace. Examples: "r:DataSources/r:DataSource[@Name='X']" / ".//r:Textbox[@Name='X']/r:Style". Returns [] when nothing matches; raises on malformed xpath.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`xpath`	Yes

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations, the description discloses key behaviors: read-only, returns [] on no match, raises on malformed XPath. This is transparent for a query tool, though it does not mention performance or limits.

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

Conciseness5/5

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

The description is two sentences plus examples, front-loading the main purpose. Every sentence adds value without fluff, making it efficiently informative.

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?

Despite no output schema, the description explains return values (serialised XML strings, [] on no match) and error behavior (raises on malformed XPath). For a read-only query tool, this is complete.

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

Parameters3/5

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

The description provides XPath context (namespaces, root element) and examples for the xpath parameter, adding value beyond the schema. However, the path parameter is not described, and schema coverage is 0%, so compensation is partial.

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 clearly states the tool performs a read-only XPath query against a report, returning matched elements as serialised XML strings. It identifies the resource (report) and action (query), distinguishing it from sibling tools like raw_xml_replace which modify.

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

Usage Guidelines3/5

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

The description implies usage for reading XML via XPath, contrasting with write tools, but does not explicitly state when to use this tool vs alternatives or provide 'when not to use' guidance.

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

refresh_dataset_fieldsA

Sync a dataset's block against the shape detected in its DAX . Eliminates the manual 'open Report Builder → right-click → Refresh Fields' step after a query rewrite. Recognises SELECTCOLUMNS aliases and Table[Col] tokens (SUMMARIZECOLUMNS / ad-hoc). Adds missing fields; lists orphans without auto-removing (caller decides what to drop). Returns {added, orphans, unchanged, warnings}. Cheap regex-based detection — bare EVALUATE 'Table' returns a warning.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`dataset_name`	Yes

TDQS

A3.8/5.0

Behavior4/5

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

No annotations provided, so description fully covers behavioral traits: adds missing fields, lists orphans without removal, returns categorical results, uses regex-based detection with warnings. Transparent about limitations like bare EVALUATE warnings.

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?

Description is informative and front-loaded with the primary action, but slightly lengthy with technical details. Still efficient and well-structured.

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

Completeness4/5

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

Given only two parameters, no output schema, and no annotations, the description provides sufficient context about behavior, return structure, and limitations. Could mention conflict handling, but overall complete.

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

Parameters2/5

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

Schema description coverage is 0%, yet description adds no semantic meaning to the two required parameters (path and dataset_name). Only restates they are required, missing an opportunity to clarify expected values or formats.

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?

Clearly states the tool syncs a dataset's Fields block from its DAX CommandText, eliminating manual Report Builder steps. Distinguishes from siblings like add_dataset_field or update_dataset_query by focusing on field synchronization from query shape.

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

Usage Guidelines3/5

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

Implicitly describes usage after query rewrites and that caller decides on orphans, but does not explicitly state when not to use or provide alternatives among the many sibling tools for field manipulation.

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

remove_body_itemA

Remove a named item (Textbox, Image, or Tablix) from /. Destructive but explicit — raises if the name doesn't match anything.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes

TDQS

A3.8/5.0

Behavior3/5

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

No annotations are provided, so the description carries full burden. It discloses destructive nature and error behavior, but lacks details on transaction requirements, reversibility, or side effects. More context would improve transparency.

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

Conciseness5/5

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

The description is a single concise sentence that immediately conveys the purpose, item types, and error behavior. No wasted words.

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

Completeness3/5

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

The tool has many siblings, and the description does not provide enough context to differentiate it (e.g., specifically for body items). The 'path' parameter is unexplained. Lacks output schema. Adequate but with gaps.

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

Parameters2/5

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

Schema description coverage is 0%. The description partially explains the 'name' parameter (must be a Textbox, Image, or Tablix), but provides no meaning for the 'path' parameter. This is insufficient for an agent to understand how to use the parameters correctly.

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 clearly states the action (remove), the resource (named item from body/report items), and specifies the item types (Textbox, Image, Tablix). It also notes the error behavior, distinguishing it from sibling tools like add_body_* or remove_footer_item.

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?

The description mentions that the tool is destructive and raises an error if the name is not found, but it does not explicitly state when to use it vs alternatives like remove_footer_item or remove_header_item. It implies use for body items only.

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

remove_calculated_fieldA

Remove a calculated by name. Refuses if the field is data-bound (carries instead of ) — those reflect the source query's columns. Drop a data-bound field via remove_dataset_field, or rewrite the dataset query via update_dataset_query.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`field_name`	Yes
`dataset_name`	Yes

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden. It transparently states that the tool refuses to remove data-bound fields and explains why. It could mention if the operation is reversible or any side effects, but the core behavior is well-covered.

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

Conciseness5/5

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

The description is two sentences long with no wasted words. Every sentence adds essential information: the main action, a refusal condition, and alternatives.

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

Completeness4/5

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

The description adequately covers the core functionality and refusal condition. However, given the lack of parameter descriptions and no output schema, it could be more helpful by explaining parameter roles. Still, it is fairly complete for a removal tool.

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

Parameters2/5

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

Schema description coverage is 0%, yet the description does not explain any parameter meanings. It only implies field_name is the name of the calculated field. path and dataset_name remain unexplained, leaving the agent to infer from context.

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 clearly states the tool removes a calculated field by name, distinguishing it from data-bound fields. It uses specific verb 'Remove' and resource 'calculated <Field>', which is distinct from sibling tools like remove_dataset_field.

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

Usage Guidelines5/5

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

The description explicitly states when to use this tool (for calculated fields) and when not (for data-bound fields). It provides clear alternative tools: remove_dataset_field for data-bound fields and update_dataset_query for rewriting the query.

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

remove_chart_seriesA

Remove a named from a chart. Refuses to remove the last remaining series (use remove_body_item to drop the whole chart instead). Returns {chart, removed, remaining}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`chart_name`	Yes
`series_name`	Yes

TDQS

A4.3/5.0

Behavior4/5

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

No annotations provided, but description discloses the refusal behavior for last series and the return format {chart, removed, remaining}. Does not mention editing transaction or side effects, but still provides useful behavioral context.

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

Conciseness5/5

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

Two sentences: first states action, second adds constraint, alternative, and return value. Front-loaded and no wasted words.

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

Completeness4/5

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

Despite no output schema and no annotations, the description covers the main action, a key constraint, an alternative, and return shape. Missing prerequisites like editing transaction, but otherwise complete for the complexity.

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

Parameters2/5

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

Schema has 0% description coverage. Parameter names (path, chart_name, series_name) are somewhat self-explanatory, but description adds no additional meaning or format details. An agent may infer, but explicit guidance is missing.

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?

Clearly states 'Remove a named <ChartSeries> from a chart' – specific verb and resource. Distinguishes from sibling remove_body_item by noting it refuses to remove the last remaining series and suggesting an alternative.

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

Usage Guidelines5/5

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

Explicitly state when not to use (last remaining series) and provides alternative (use remove_body_item). No prerequisites listed, but the constraint is clearly communicated.

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

remove_column_groupA

Inverse of add_column_group: unwraps a column-axis group's children back to the top of the column hierarchy and removes the matching body column at position 0 (along with each row's first cell). Errors if group_name only exists on the row axis.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`group_name`	Yes
`tablix_name`	Yes

TDQS

A4.1/5.0

Behavior5/5

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

With no annotations, the description effectively details the tool's effects: unwrapping children, removing a column, and deleting cells. It also warns about an error scenario, providing full behavioral transparency.

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

Conciseness5/5

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

The description is two sentences, each serving a purpose: stating the primary action and listing an error condition. No unnecessary words.

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

Completeness2/5

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

Given no annotations, no output schema, and three required parameters with zero schema description, the description is incomplete. It omits essential parameter semantics and return values, leaving the agent underinformed.

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

Parameters2/5

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

The description only explains the group_name parameter by referencing the error condition. It does not describe the path or tablix_name parameters, which have 0% schema coverage and require explanation for correct usage.

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 clearly states it is the inverse of add_column_group, specifying the exact action: unraveling children, removing a column at position 0 and associated cells. This distinguishes it from sibling tools like remove_row_group.

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?

The description implies usage as an inverse operation and notes an error condition (if group_name only on row axis). However, it lacks explicit guidance on when not to use it or alternatives, though the inverse mention provides context.

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

remove_dataset_fieldA

Remove a data-bound by name (one with ). Symmetric counterpart to remove_calculated_field. Refuses on calculated fields (use remove_calculated_field instead) and on still-referenced fields (any expression containing Fields!.Value / .IsMissing / .Count). Pass force=True to delete anyway. Closes the cookbook flow: refresh_dataset_fields lists orphans, remove_dataset_field drops them. Returns {dataset, removed, kind: 'DataBoundField'}.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`force`	No	Default false: refuse if the field is still referenced anywhere. true: delete anyway (prefer fixing the references first).
`field_name`	Yes
`dataset_name`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It adequately describes refusal conditions, the force option, and the return value structure. However, it does not explicitly mention permissions, reversibility, or side effects beyond deletion, which slightly lowers the score.

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

Conciseness5/5

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

The description is concise (5 sentences) and well-structured: first sentence states the main action, second contrasts with a sibling, third explains refusal, fourth explains the force parameter, and fifth describes the flow and return. No unnecessary information.

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?

Given the tool's complexity and lack of output schema, the description provides complete context: it explains when the tool is used in the cookbook flow, the conditions for refusal, the return format, and integrates with sibling tools. No major gaps are present.

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

Parameters3/5

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

With only 25% schema description coverage, the description adds some context by explaining the purpose of field_name and force, but it does not explicitly describe path and dataset_name beyond being required. The description provides moderate value but does not fully compensate for the low schema coverage.

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 clearly states the action (remove a data-bound field by name) and distinguishes it from siblings like remove_calculated_field. It specifies the target type (data-bound) and the conditions for refusal, making the tool's purpose unambiguous.

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

Usage Guidelines5/5

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

Explicitly states when to use (data-bound fields) and when not (calculated fields, still-referenced fields). It names the alternative tool (remove_calculated_field) and explains the optional force parameter for forced deletion. The cookbook flow context further guides usage.

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

remove_dataset_filterA

Remove a dataset-level filter by its 0-based document-order index. Cleans up the empty block when removing the last entry.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`dataset_name`	Yes
`filter_index`	Yes

TDQS

A3.5/5.0

Behavior3/5

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

Description discloses cleanup behavior but lacks details on error handling (e.g., invalid index), side effects, or permissions. With no annotations, it partially carries the burden but leaves gaps.

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

Conciseness5/5

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

Two sentences, no fluff. Efficiently conveys the core action and a key behavioral detail.

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

Completeness3/5

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

Adequate for a simple removal, but missing references to related tools (list_dataset_filters), behavior on invalid index, and the distinction from tablix-level filters.

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

Parameters3/5

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

Only filter_index gets additional context ('0-based document-order index'). Path and dataset_name have no semantic addition beyond the schema. With 0% schema coverage, description should compensate more fully.

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?

Description clearly states removal of a dataset-level filter by its 0-based document-order index, distinguishing it from siblings like remove_tablix_filter. It also notes cleanup of empty <Filters> block, adding specificity.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool vs alternatives. Does not mention prerequisite use of list_dataset_filters to obtain the index, nor any conditions or exclusions.

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

remove_data_sourceA

Remove a named . Refuses by default if any DataSet/Query/DataSourceName or DataSource/DataSourceReference still references it; the error lists the offending locators. Pass force=True to remove anyway.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`force`	No

TDQS

A3.8/5.0

Behavior3/5

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

With no annotations, the description carries full burden. It discloses refusal on references and the force option, but lacks details on permissions, reversibility, or post-removal state. The behavioral disclosure is adequate but not comprehensive.

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

Conciseness5/5

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

Two sentences, front-loaded with the action, and every phrase adds value. No redundancy or unnecessary information. Highly concise and structured.

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

Completeness3/5

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

The description covers the core behavior and force option, but misses details like what constitutes a valid path, success indication, and whether the action is reversible. For a tool with no output schema and no annotations, more context is needed for full completeness.

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

Parameters2/5

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

Schema coverage is 0%, so the description should compensate. It explains 'force' partially, but 'name' and 'path' are not described beyond naming the DataSource. The meaning of 'path' is unclear, and the format of 'name' is not specified.

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 clearly states 'Remove a named <DataSource>', which is a specific verb-resource pairing. It distinguishes from sibling tools like add_data_source or rename_data_source, and the context of removing a data source is unambiguous.

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?

The description explains the default refusal behavior and how to override with force=True, providing clear context for when to use the tool. Though it doesn't explicitly state alternatives, the name and context imply this is the only removal tool for data sources.

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

remove_embedded_imageA

Remove a named embedded image. Refuses (lists offending Image elements) when any =name> still references it; pass force=True to remove anyway and accept the dangling references. Drops the empty block when removing the last entry.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`force`	No

TDQS

A3.9/5.0

Behavior4/5

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

With no annotations, the description fully carries the burden and discloses key behaviors: removal, refusal with listing of offending elements, force flag to accept dangling references, and cleanup of empty block. No contradictions.

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 description is efficient with three sentences, covering essential behavior without fluff. However, it could be slightly more structured by explicitly listing parameters.

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

Completeness3/5

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

The description is adequate for the tool's simplicity, covering behavioral details but missing the 'path' parameter explanation and return value information. It is not fully complete.

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

Parameters2/5

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

Schema coverage is 0%, so the description must explain all parameters. It explains 'force' and implies 'name', but fails to explain the required 'path' parameter, leaving a significant gap.

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 clearly states the verb 'Remove' and the resource 'named embedded image', distinguishing it from siblings like 'remove_body_item' and 'add_embedded_image'.

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?

The description provides clear context for when to use the tool, including the refusal behavior when references exist and the option to force removal. However, it does not explicitly state when not to use it or mention alternatives.

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

remove_footer_itemC

Same as remove_header_item, for .

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes

TDQS

C2.4/5.0

Behavior2/5

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

No annotations are present, so the description carries the full burden. It does not disclose any behavioral traits such as prerequisites, side effects, or safety concerns (e.g., whether this is destructive). The description only mentions the target element, lacking transparency.

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

Conciseness3/5

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

The description is extremely concise (one sentence), but it is not self-contained as it references another tool. It lacks a direct statement of the action. Conciseness is good, but clarity is compromised.

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

Completeness2/5

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

For a simple tool with 2 parameters and no output schema, the description should at least specify what 'name' and 'path' refer to. It does not, leaving the agent under-informed. The minimum viable completeness is not achieved.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not add any meaning to the 'name' and 'path' parameters. Without explanation, the agent must infer their roles, which is insufficient.

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

Purpose4/5

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

The tool name 'remove_footer_item' clearly indicates removal of a footer item. The description adds context by referencing 'remove_header_item' and specifying 'for <PageFooter>', making the purpose clear. However, the description relies on knowledge of the sibling tool for full clarity.

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

Usage Guidelines2/5

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

No guidelines are provided on when to use this tool versus alternatives like remove_body_item or remove_header_item. The context of sibling tools is present, but the description offers no explicit differentiation or usage context.

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

remove_header_itemB

Remove a named Textbox or Image from /. Empties the ReportItems block when the last item leaves.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes

TDQS

B3.4/5.0

Behavior3/5

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

Without annotations, the description carries the full burden. It adds a behavioral detail about emptying the ReportItems block when the last item leaves, but does not disclose other important traits like reversibility, editing mode requirements, or error conditions.

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

Conciseness5/5

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

Two concise sentences front-loading the main action and a key side effect. No unnecessary words.

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

Completeness3/5

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

While it covers the basic action and a side effect, it omits return value information and detailed parameter guidance. For a tool with no output schema and undocumented parameters, more completeness is needed.

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

Parameters2/5

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

Schema descriptions coverage is 0%, so the description must compensate. It only hints that 'name' identifies the item ('named'), but does not explain the 'path' parameter. Minimal added meaning beyond the schema.

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 clearly states the verb 'Remove' and the resource 'named Textbox or Image from <PageHeader>/<ReportItems>'. It differentiates from sibling tools like remove_body_item and remove_footer_item by specifying the header context.

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool vs alternatives like remove_body_item or remove_footer_item. The description only states what it does, not when or when not to use it.

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

remove_parameterA

Remove a ReportParameter by name. Refuses (lists offending locators) if the parameter is still referenced anywhere in the report by Parameters!.Value or .Label. Pass force=True to remove anyway.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`force`	No

TDQS

A4.2/5.0

Behavior4/5

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

Without annotations, description effectively discloses refusal behavior based on references and force option. Success behavior is implied but return value not specified.

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

Conciseness5/5

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

Two concise sentences with key details front-loaded. No extraneous information.

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

Completeness4/5

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

Adequate for a simple removal tool with 3 params and no output schema. Covers main behavior and edge case, but lacks details on success output.

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

Parameters3/5

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

Name and force are explained via context, but path is not described. With 0% schema coverage, some gaps remain despite partial compensation.

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?

Specific verb 'Remove' and resource 'ReportParameter' clearly stated. Distinguishes from siblings by specifying the object type and behavior.

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?

Clear context for use (removing parameters) and when to avoid (if referenced) with alternative force flag. No explicit mention of when to use other tools, but siblings are distinct.

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

remove_query_parameterB

Remove a query parameter from a dataset. Cleans up the empty block when removing the last one.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`dataset_name`	Yes

TDQS

B3.1/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It explicitly discloses that 'Cleans up the empty <QueryParameters/> block when removing the last one', which is a specific and useful behavioral trait beyond basic deletion. This adds value and context about side effects.

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

Conciseness5/5

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

Two short sentences that front-load the main purpose and add a key behavioral detail. No wasted words. Highly efficient and scannable.

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

Completeness2/5

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

Given the tool has three required parameters with zero schema coverage and no output schema, the description is far too minimal. It lacks explanations of parameter roles, return behavior, error conditions, or prerequisites (e.g., does the parameter need to exist?). Completeness is insufficient for reliable tool usage.

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

Parameters1/5

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

Schema description coverage is 0%, yet the description provides zero information about any of the three required parameters (name, path, dataset_name). The agent must rely solely on parameter names, which are insufficient for correct invocation. This is a critical gap.

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

Purpose4/5

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

The description clearly states the action ('Remove a query parameter from a dataset') and adds a specific behavioral detail about cleanup. However, it does not distinguish this tool from sibling tools like 'remove_parameter' which likely removes a different kind of parameter. The purpose is clear but lacks sibling differentiation.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives (e.g., update_query_parameter or remove_parameter). The description only states what the tool does without any conditional or contextual advice. There is no explicit when/when-not or alternative naming.

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

remove_row_groupA

Inverse of add_row_group: unwraps a group's children back to its parent hierarchy and removes the matching header row at body row 0. Refuses to remove the conventional Details group.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`group_name`	Yes
`tablix_name`	Yes

TDQS

A3.6/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It discloses a key behavioral trait (refuses to remove the Details group) and explains the hierarchical impact. However, it does not mention side effects, error conditions, or transaction requirements.

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

Conciseness5/5

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

Two compact sentences that front-load the core purpose and include a notable constraint. Every word serves a purpose with no redundancy.

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

Completeness3/5

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

Given the tool's complexity (three required params, no output schema), the description provides essential behavioral context but lacks return value information, transaction requirements, and parameter details, making it adequate but not comprehensive.

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

Parameters1/5

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

Schema coverage is 0% with no parameter descriptions. The description adds no information about the three parameters (path, tablix_name, group_name), leaving the agent without guidance on their meaning or format.

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 clearly states the tool is the inverse of add_row_group, explains the action (unwraps children, removes header row), and adds a specific constraint (refuses to remove the Details group). This distinguishes it from sister tools like remove_column_group.

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

Usage Guidelines3/5

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

The description implies usage context by linking to add_row_group, but does not explicitly state when to use this tool vs alternatives, nor does it provide exclusions or prerequisites.

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

remove_tablix_columnA

Remove the tablix column whose data-row cell holds a textbox named column_name. Drops the matching TablixColumn, removes the top-level TablixMember at that column index (only if it's a leaf, never a column group wrapper), and removes the cell at that index from every TablixRow. Errors if no row contains a textbox with the given name.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`column_name`	Yes
`tablix_name`	Yes

TDQS

A3.8/5.0

Behavior4/5

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

The description discloses the destructive behavior (drops column, member only if leaf, cells from all rows) and error conditions. It does not mention side effects, permissions, or transaction context, but given no annotations, transparency is above average.

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

Conciseness5/5

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

Three sentences efficiently explain the action, details, and error condition. No fluff. Each sentence adds value, and the key verb is front-loaded.

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

Completeness3/5

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

The description covers the core operation well but omits explanation of two parameters ('path', 'tablix_name') and does not mention the need for an editing transaction (sibling tools indicate transaction management). Return value is not addressed but no output schema exists.

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

Parameters2/5

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

Schema description coverage is 0%, so description must explain all parameters. Only 'column_name' is explained in context. 'path' and 'tablix_name' are not described, leaving the agent to infer their meaning. This is a significant gap.

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 clearly states the verb 'Remove' and the resource 'tablix column'. It specifies the exact condition (based on textbox name) and details what is removed (column, member if leaf, cells). This distinguishes it from sibling tools like remove_column_group or remove_tablix_filter.

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

Usage Guidelines3/5

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

The description implies usage when you want to remove a column identified by a textbox in its data cell, and error conditions are given. However, it does not explicitly guide when to use this tool versus alternatives (e.g., remove_column_group for groups) or mention prerequisites like an active editing transaction.

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

remove_tablix_filterA

Remove a filter by index. Filters are anonymous in RDL, so use list_tablix_filters first to find the right index. Removing the last filter also drops the empty block.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`tablix_name`	Yes
`filter_index`	Yes

TDQS

A3.8/5.0

Behavior3/5

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

Describes the behavioral detail that removing the last filter drops the empty '<Filters/>' block, which is valuable given no annotations. However, it does not disclose potential side effects, permissions, or return behavior.

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

Conciseness5/5

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

Two compact sentences. First sentence states the core purpose; second sentence provides essential usage guidance and a behavioral note. No redundancy or unnecessary information.

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

Completeness3/5

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

Adequate for a simple removal tool, but lacks information on return values, error cases, or confirmation of removal. No output schema is provided. Given the complexity of sibling tools, it could be more comprehensive.

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

Parameters2/5

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

The description does not elaborate on the three parameters beyond the schema. 'filter_index' is implied to be the index, but no details on format or relation to other parameters. Schema coverage is 0%, so the description fails to add value.

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?

Explicitly states the action (remove) and resource (filter by index). Distinguishes from sibling tools like 'remove_dataset_filter' by specifying 'tablix_filter'. Includes context about RDL anonymity, reinforcing the specific use case.

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?

Provides a clear precondition: use 'list_tablix_filters' to find the correct index. Does not explicitly state when not to use or mention alternative methods, but the context is sufficient for proper usage.

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

rename_data_sourceA

Rename a and rewrite every reference: DataSet/Query/DataSourceName entries AND any DataSource/DataSourceReference shared-source links. Atomic: stages all matches before committing. Errors if new_name already exists or equals old_name.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`new_name`	Yes
`old_name`	Yes

TDQS

A4.4/5.0

Behavior5/5

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

With no annotations, the description fully discloses behavioral traits: it rewrites all references atomically, stages matches before committing, and errors on duplicate or identical names. This provides sufficient transparency for safe invocation.

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

Conciseness5/5

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

Two sentences with no fluff. The first sentence states the primary action and scope, the second adds atomicity and error details. Every sentence provides value.

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

Completeness4/5

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

The description covers the core behavior, side effects, atomicity, and error conditions. It lacks details about the return value or confirmation, but given no output schema, this is a minor gap. Overall, it is adequate for a rename tool.

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

Parameters3/5

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

The description adds meaning for 'old_name' and 'new_name' implicitly through the rename action, but it does not explain the 'path' parameter, which is required. With 0% schema coverage, the description should clarify all three parameters.

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 clearly states the verb 'Rename' and the resource 'DataSource'. It distinguishes itself from sibling tools by detailing that it rewrites all references (DataSet/Query/DataSourceName entries and shared-source links), which is unique among data source tools.

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?

The description provides clear context for when to use the tool (rename operation with automatic reference rewriting). It explicitly mentions error conditions (new_name already exists or equals old_name), but does not explicitly contrast with alternatives or provide when-not-to-use guidance.

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

rename_parameterA

Rename a ReportParameter and rewrite every textual occurrence of Parameters!.Value / .Label across the entire report. Case-sensitive. Atomic: collects all matches first, then commits. Errors if new_name already exists or equals old_name.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`new_name`	Yes
`old_name`	Yes

TDQS

A4.3/5.0

Behavior5/5

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

With no annotations, the description fully discloses behavioral traits: it rewrites text, is case-sensitive, atomic (collects then commits), and errors if new_name exists or equals old_name. This is comprehensive for a mutation tool.

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

Conciseness5/5

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

Two sentences with no wasted words. Front-loaded with the main action, every sentence adds value: renaming, rewriting, case-sensitivity, atomicity, error conditions.

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?

Given 3 required params, no output schema, and no nested objects, the description covers scope, case-sensitivity, atomicity, and error conditions completely. No gaps in understanding the tool's behavior.

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

Parameters3/5

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

Schema coverage is 0%, so the description must add meaning. It explains old_name and new_name roles but does not describe the 'path' parameter, leaving ambiguity about its purpose.

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 clearly states the tool renames a ReportParameter and rewrites all textual occurrences of Parameters!<old_name>.Value/.Label across the report. It specifies case-sensitivity and atomicity, distinguishing it from siblings like rename_data_source.

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

Usage Guidelines3/5

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

The description implies usage through its action but provides no explicit when-to-use or when-not-to-use guidance, nor alternatives. It only mentions error conditions, not context for selection.

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

reorder_parametersA

Reorder children to match the supplied names list. names MUST be a permutation of every existing parameter — no missing, no duplicates, no unknown names. When a exists, its CellDefinition entries are reordered in lockstep so the parameter pane shows fields in the new declaration order. RowIndex / ColumnIndex are not recomputed (RB's layout grid is independent of declaration order). Returns {order, kind, changed: bool}; same order → no save.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`names`	Yes

TDQS

A4/5.0

Behavior4/5

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

Discloses lockstep layout reordering, notes RowIndex/ColumnIndex not recomputed, and describes return value. No annotations, so description carries full burden.

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?

Concise with front-loaded purpose. No redundant sentences; could be slightly tighter but effective.

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

Completeness3/5

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

Missing explanation for 'path' parameter given no schema description coverage. Return value described but parameter documentation gap reduces completeness.

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

Parameters3/5

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

Thoroughly explains 'names' parameter with constraints, but 'path' parameter (required) is not described at all. Schema coverage 0% so description should compensate.

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?

Clearly states verb 'Reorder' and resource '<ReportParameter> children', distinct from sibling tools like remove_parameter or rename_parameter.

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?

Provides explicit constraint: 'names MUST be a permutation of every existing parameter'. Implies when to use, though no explicit alternative mentioned.

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

restore_from_backupA

Restore a backup file over its original target. target_path defaults to the path implied by the backup's .bak. filename; pass target_path explicitly when the backup name doesn't match that shape. Refuses if target mtime is newer than backup (staleness guard) — pass force=True to override. Returns {source, restored_to, bytes_restored}.

ParametersJSON Schema

Name	Required	Description	Default
`force`	No
`backup_path`	Yes
`target_path`	No

TDQS

A4.3/5.0

Behavior3/5

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

The description discloses key behaviors: the staleness guard (refuses if target mtime is newer) and force override, and the return format. However, it does not mention idempotency, permission requirements, or potential side effects (e.g., overwriting files). Given no annotations, more transparency would improve the score.

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

Conciseness5/5

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

Three sentences, no fluff. The first sentence states the action, the second handles default logic, and the third covers the staleness guard and return. Perfectly structured for quick parsing.

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

Completeness4/5

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

The description covers the main usage scenarios (default path, override, force) and specifies return values. It lacks details about error conditions (e.g., missing backup file) but given the tool's simplicity, it is mostly complete. No output schema, so return description helps.

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?

The schema has 0% description coverage, so the description carries the full burden. It explains all three parameters: backup_path (implied), force (overrides guard), and target_path (default derivation and explicit override). This adds crucial meaning beyond the schema.

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 clearly states the tool's purpose: 'Restore a backup file over its original target.' It provides a specific verb and resource, and distinguishes this tool from siblings like backup_report, which creates backups instead of restoring. No ambiguity.

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?

The description explains when to use the default target_path and when to override it, and when to use force=True to bypass the staleness guard. It implicitly guides usage by describing the staleness guard behavior, but does not explicitly contrast with other tools or state prerequisites. Slightly incomplete.

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

set_alternating_row_colorA

Zebra-stripe a tablix's detail row by writing BackgroundColor=IIf(RowNumber(Nothing) Mod 2, color_a, color_b) on every detail cell's Textbox. Walks the row hierarchy to find the Details leaf — works after add_row_group nests the structure deeper. Replaces any existing BackgroundColor.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`color_a`	Yes	Odd-row color, e.g. '#F2F2F2'.
`color_b`	Yes	Even-row color, e.g. '#FFFFFF'.
`tablix_name`	Yes

TDQS

A3.9/5.0

Behavior4/5

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

With no annotations, the description carries full burden. It discloses the implementation detail (IIf expression), hierarchy walking, and that it replaces existing BackgroundColor, providing good behavioral insight.

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

Conciseness5/5

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

Three sentences with no fluff. The core action is front-loaded, and each sentence adds value.

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

Completeness3/5

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

No output schema; description adequately covers the tool's function and constraints (works after add_row_group, replaces colors). Lacks error handling or prerequisite details.

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

Parameters3/5

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

Schema coverage is 50% (color_a and color_b have descriptions). The description adds no extra meaning for path or tablix_name beyond schema, so it does not compensate for the missing parameter descriptions.

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 clearly states the tool zebra-stripes a tablix's detail row by setting BackgroundColor expression on detail cells. It distinguishes from siblings like set_conditional_row_color and set_detail_row_visibility by specifying the mechanism.

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

Usage Guidelines3/5

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

The description provides context that it works after add_row_group and replaces existing BackgroundColor, but does not explicitly state when to use this tool versus alternatives like set_conditional_row_color.

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

set_body_item_positionA

Move an existing named ReportItem inside to (top, left). Preserves all other properties (size, style, group structure). top and left are passed through verbatim — RDL accepts any size unit (2cm, 0.75in, 108pt). Errors if no body item by that name.

ParametersJSON Schema

Name	Required	Description	Default
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It discloses that properties are preserved, top/left accept any RDL size unit, and an error occurs if the item doesn't exist. It does not mention transaction requirements, return values, or auth, but the disclosed traits are useful and accurate.

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

Conciseness5/5

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

Three sentences, front-loaded with purpose, then details, then error condition. No wasted words. Efficient and clear.

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

Completeness4/5

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

The description is nearly complete given the 4 parameters, no output schema, and no annotations. It covers purpose, key parameter behavior, and an error condition. Missing explicit path explanation and behavioral context like transaction state, but overall adequate.

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

Parameters3/5

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

Schema coverage is 0%, so description must compensate. It explains top, left (any unit), and name (existing item in Body). However, the 'path' parameter is not explained; its role is only implied by 'inside <Body>'. Partial coverage of the 4 parameters.

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 clearly states the verb 'move' and the resource 'existing named ReportItem inside <Body>' to target coordinates. It distinguishes from sibling tools like set_body_item_size and add_body_image by specifying it changes position while preserving other properties.

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?

The description implies when to use (move without altering size/style) but does not explicitly state when not to use or name alternatives. The sibling set_body_item_size is implicitly distinguished by the phrase 'preserves all other properties'. Somewhat clear but not fully explicit.

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

set_body_item_sizeA

Resize an existing named ReportItem inside . At least one of width / height must be supplied; missing fields are left untouched. Same RDL size-string convention as the position tools.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`width`	No
`height`	No

TDQS

A4.2/5.0

Behavior3/5

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

No annotations are provided, so the description fully shoulders the transparency burden. It clearly indicates mutation (resizing), but lacks details on error conditions, permissions, or side effects beyond 'left untouched'.

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

Conciseness5/5

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

Two sentences with zero wasted words. The verb 'Resize' leads, then constraints and conventions are efficiently stated.

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

Completeness4/5

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

Given the moderate complexity and many sibling tools, the description adequately differentiates and explains usage. It references conventions for clarity. No output schema is fine for a mutation tool with simple return.

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 provides parameter names and types but no descriptions (0% coverage). The description adds meaning: at least one of width/height must be supplied, and the format follows the same convention as position tools, which compensates for the schema's lack of detail.

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?

Description clearly states the action ('Resize an existing named ReportItem inside <Body>') and the scope ('at least one of width / height must be supplied; missing fields are left untouched'). It distinguishes from sibling tools like set_body_item_position by focusing on size vs position.

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 states that at least one of width/height must be supplied and missing fields are untouched. References the RDL size-string convention for consistency, though it does not explicitly contrast with alternatives like set_body_item_position.

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

set_body_sizeA

Set the body's rendering region inside the page. / and / (the sibling of ) — both are RDL size strings (e.g. '14in', '9in', '297mm'). Either or both kwargs required. Distinct from set_page_setup (which sets the paper chrome //) and set_body_item_size (size of items inside the body). Use this when a wide tablix or chart needs the body region expanded — without it the right edge is clipped at preview time. Idempotent: same value → empty changed. Returns {kind: 'Body', changed: list[str]}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`width`	No
`height`	No

TDQS

A4.3/5.0

Behavior4/5

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

No annotations are provided, so the description carries full burden. It discloses idempotency, return format, and gives example values for parameters. However, it does not mention error states, required permissions, or potential side effects like clipping resolution.

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 description is moderately sized and front-loaded with the main action. While some information (RDL strings) could be integrated more efficiently, the structure is logical and each sentence adds value.

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

Completeness4/5

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

For a tool with 3 parameters and no output schema, the description covers the return format, idempotency, and scaling scenario. Missing details like error handling or expected behavior when parameters are out of range.

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

Parameters3/5

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

Schema coverage is 0% (no parameter descriptions). The description adds meaning by specifying that width and height are RDL size strings with examples, and notes that either or both are required. However, the path parameter is not explained, leaving a gap.

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 clearly states the verb 'Set' and resource 'body's rendering region', and explicitly distinguishes from sibling tools set_page_setup and set_body_item_size by naming them and contrasting their purposes.

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

Usage Guidelines5/5

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

The description explicitly says when to use: 'Use this when a wide tablix or chart needs the body region expanded — without it the right edge is clipped at preview time.' It also contrasts with related tools, providing clear context for selection.

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

set_cell_spanA

Set and/or on a tablix cell. The cell is addressed by (row_index, column_name) where column_name is the textbox name inside the cell. At least one of row_span / col_span must be supplied; both must be >= 1. Pass 1 to explicitly reset a span. Replaces existing values if present.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`col_span`	No
`row_span`	No
`row_index`	Yes
`column_name`	Yes
`tablix_name`	Yes

TDQS

A4/5.0

Behavior3/5

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

With no annotations, the description must cover behavioral traits. It states 'Replaces existing values if present,' indicating idempotency. However, it does not disclose potential side effects like reflow or failure modes (e.g., invalid cell address), leaving a gap.

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

Conciseness5/5

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

The description is three sentences, each carrying essential information: purpose, addressing method, and value constraints. It is front-loaded and contains no redundancy or unnecessary words.

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

Completeness4/5

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

Given the tool's simplicity (setting a cell span) and absence of output schema, the description covers the core: how to specify the cell, constraints on span values, and replacement behavior. It does not mention error handling, but for a targeted setter, this is sufficient.

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

Parameters3/5

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

Schema coverage is 0%, so the description must explain parameters. It explains row_index and column_name via addressing, and row_span/col_span constraints. However, the 'path' and 'tablix_name' parameters are not described, leaving two of six parameters undocumented.

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 clearly states the action: 'Set <RowSpan> and/or <ColSpan> on a tablix cell.' It specifies the cell addressing method with row_index and column_name. This verb-resource combination is specific and distinguishes it from sibling tools, none of which target cell span.

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?

The description provides explicit usage constraints: at least one of row_span or col_span must be supplied, both must be >= 1, and passing 1 resets a span. It does not discuss when to avoid using this tool or mention alternatives, but the narrow purpose reduces the need.

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

set_chart_axisA

Configure a chart axis: title (Caption), format (numeric/date format string in /), min/max range, log_scale, interval, visible. axis ∈ {Category, Value}; axis_name defaults to 'Primary' (the only axis the template emits — pass a real name for secondary axes). All field args are optional; pass '' to clear an element. Returns {chart, axis, axis_name, kind, changed: list[str]} with the affected sub-element names.

ParametersJSON Schema

Name	Required	Description	Default
`max`	No
`min`	No
`axis`	Yes	Category or Value
`path`	Yes
`title`	No
`format`	No	Numeric/date format, e.g. '#,0.00' or 'MMM yyyy'.
`visible`	No
`interval`	No
`axis_name`	No		Primary
`log_scale`	No
`chart_name`	Yes

TDQS

A4.2/5.0

Behavior3/5

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

No annotations present, so description carries burden. It discloses return structure and clearing behavior via empty strings, but does not mention permissions, destructiveness, or whether changes are reversible. Adequate but not comprehensive.

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

Conciseness5/5

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

Two concise sentences, front-loaded with purpose, no filler. Every sentence adds value: first lists configuration options, second gives critical usage details.

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

Completeness4/5

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

Given 11 parameters, 3 required, and no output schema, the description covers purpose, key parameters, and return format. Lacks explanation for path/chart_name and effect on existing settings, but mostly complete for effective use.

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 low (18%), but description adds meaning for axis (Category/Value), axis_name (default Primary, secondary by name), format (in <Style>/<Format>), and clearing via empty strings. Some parameters (path, chart_name) remain implicit, but overall compensates well.

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 clearly states the verb 'configure' and the resource 'chart axis', explicitly lists configurable elements (title, format, min/max, etc.), and distinguishes between Category/Value axes and the axis_name default, differentiating it from sibling tools like set_chart_title.

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?

Provides guidance on axis_name default vs. secondary axes, and clarifies that passing empty string clears elements. Lacks explicit when-not-to-use or comparisons to alternatives, but context is clear.

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

set_chart_data_labelsA

Configure on one or all series in a chart. When series_name is None, the change applies to every series; otherwise only the named series. visible writes true|false; visible_expression writes the same element with a VB.NET =IIf(...) expression (mutually exclusive with visible). format writes /; pass '' to clear. v0.4: position ∈ Auto/Top/TopLeft/TopCenter/TopRight/Left/Center/Right/BottomLeft/BottomCenter/BottomRight/Bottom/Outside; use_value_as_label ∈ true/false; font_weight + color write to / and / (pass '' to clear). Returns {chart, series, kind, changed}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`color`	No
`format`	No
`visible`	No
`position`	No
`chart_name`	Yes
`font_weight`	No
`series_name`	No
`use_value_as_label`	No
`visible_expression`	No

TDQS

A4.1/5.0

Behavior4/5

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

No annotations provided, so the description carries the burden. It discloses important behavioral details: mutual exclusivity between visible and visible_expression, that format accepts '' to clear, the list of valid position values, and the return value. This provides sufficient transparency beyond the schema.

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 description is moderately lengthy but well-structured, starting with the main purpose and then detailing parameter behaviors. It uses clear language and bullet-like enumeration for version-specific additions. Minor redundancy in listing position values could be trimmed.

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

Completeness4/5

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

Given the tool's complexity (10 parameters, mutual exclusivity, clearing behavior) and lack of output schema, the description covers return value and key behaviors comprehensively. It provides version context and explains how to clear format, though it omits handling of some less common parameters like visible_expression beyond mutual exclusivity.

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?

With 0% schema description coverage, the description adds significant meaning for most parameters: visible/visible_expression mutual exclusivity, format clearing, position enum values, use_value_as_label boolean, and font_weight/color writing to Style elements. Some parameters like path, chart_name, and series_name lack elaboration, but schema provides type info.

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 clearly states the tool's purpose: configure ChartDataLabel on one or all series in a chart. It distinguishes behavior based on series_name (None applies to all, named applies to that series) and lists key parameters, effectively differentiating it from sibling tools like set_chart_series_type or set_chart_title.

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

Usage Guidelines3/5

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

The description explains the logic for applying to all or one series but does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites or exclusions. This lack of comparative context leaves room for ambiguity.

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

set_chart_legendA

Configure a chart legend: position (TopLeft / TopCenter / TopRight / LeftTop / LeftCenter / LeftBottom / RightTop / RightCenter / RightBottom / BottomLeft / BottomCenter / BottomRight) and visible (writes true|false). legend_name defaults to 'Default' (the only one the template emits). Returns {chart, legend, kind, changed: list[str]}; no-op short-circuit when nothing supplied.

ParametersJSON Schema

Name	Required	Default
`path`	Yes
`visible`	No
`position`	No
`chart_name`	Yes
`legend_name`	No	Default

TDQS

A3.6/5.0

Behavior4/5

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

With no annotations provided, the description discloses key behaviors: default values ('Default' for legend_name), short-circuit on no input, and return format. It also lists all 12 position options. However, it does not mention permission requirements or side effects like overwriting existing legend settings.

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 description is a single sentence packed with information, including enums, defaults, return type, and edge case. It is efficient but could be more readable by splitting into two sentences. No verbosity.

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

Completeness3/5

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

Given no output schema and 5 parameters with 0% coverage, the description covers the key parameters and return value. However, it omits context for path and chart_name, and does not mention prerequisites like being in an editing transaction (common among sibling tools). Some missing details for completeness.

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

Parameters3/5

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

Schema coverage is 0%, so description must add value. It explains position options, visible's XML effect, and legend_name's default. However, path and chart_name parameters are not described beyond schema. The description partially compensates for the lack of schema annotations.

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

Purpose4/5

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

The description clearly states the tool's purpose: configure a chart legend with position, visibility, and name. It specifies the exact attributes and their allowed values. However, it does not differentiate from other set_chart_* sibling tools, which also modify chart properties.

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

Usage Guidelines3/5

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

The description implies usage for configuring a chart legend but lacks explicit guidance on when to use this tool versus alternatives like set_chart_title or set_chart_axis. No when-not-to-use scenarios are provided.

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

set_chart_paletteA

Set on a chart. palette ∈ Default / EarthTones / Excel / GrayScale / Light / Pastel / SemiTransparent / Berry / Chocolate / Fire / SeaGreen / BrightPastel. Pass '' to clear (RB falls back to its built-in default palette). Returns {chart, kind, changed: bool}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`palette`	Yes
`chart_name`	Yes

TDQS

A3.7/5.0

Behavior3/5

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

No annotations are provided, so the description must disclose behavioral traits. It mentions the return structure and the effect of passing an empty string (clears to default). Lacks details on side effects, permissions, or error conditions, but is adequate for a simple setter.

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

Conciseness5/5

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

The description is extremely concise with two sentences, no filler, and front-loads the purpose. Every sentence adds value.

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

Completeness2/5

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

Given three required parameters with zero schema descriptions and no output schema, the description fails to clarify 'path' and 'chart_name' or indicate return value details beyond a snippet. It is incomplete for an agent to confidently invoke without additional context.

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

Parameters2/5

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

Schema description coverage is 0%, yet the description only implicitly describes the 'palette' parameter via the allowed values. It does not explain 'path' or 'chart_name', leaving significant ambiguity.

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 clearly states 'Set <Palette> on a chart,' specifying the verb, resource, and property. It lists acceptable palette values, distinguishing it from sibling tools like set_chart_series_color and set_chart_axis.

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?

Provides explicit guidance on palette values and how to clear the palette by passing an empty string. However, it does not explicitly state when to use this tool versus alternatives or when not to use it.

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

set_chart_series_actionA

Set / to a Hyperlink (URL), Drillthrough (another report + optional parameters), or BookmarkLink. Same kwarg surface as set_textbox_action / set_image_action; the chart series is addressed by (chart_name, series_name). Schema-aware insertion respects ChartSeries child order. Idempotent on structural equality of the inner block.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`chart_name`	Yes
`action_type`	Yes
`series_name`	Yes
`target_expression`	Yes
`drillthrough_parameters`	No

TDQS

A3.6/5.0

Behavior3/5

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

With no annotations provided, the description adds behavioral context: schema-aware insertion respects ChartSeries child order and the operation is idempotent on structural equality. However, it does not disclose side effects, permission requirements, or error behavior.

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 description is three sentences: first states the core purpose, second clarifies similarity and addressing, third adds behavioral notes. It is front-loaded and efficient, though the reference to sibling tools could be considered slight redundancy.

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

Completeness3/5

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

Given the tool has 6 parameters (5 required) and no output schema, the description covers action types, addressing, idempotency, and child order. However, it lacks full parameter explanations and does not describe return values, leaving gaps for an agent unfamiliar with sibling tools.

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

Parameters3/5

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

Schema description coverage is 0%, so the description must compensate. It explains the action_type enum values, implies drillthrough_parameters is optional for Drillthrough, and defines addressing via chart_name and series_name. However, it does not detail the other parameters (path, target_expression), relying on the user's familiarity with sibling tools.

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 clearly states the tool sets an action (Hyperlink, Drillthrough, BookmarkLink) on a ChartSeries. It distinguishes itself from sibling tools like set_textbox_action and set_image_action by specifying the addressing pattern (chart_name, series_name) and shared kwarg surface.

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

Usage Guidelines3/5

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

The description implies usage for chart series actions by mentioning the addressing pattern and similarity to other action-setting tools, but it does not explicitly state when to use this tool versus alternatives or when not to use it.

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

set_chart_series_groupingA

Promote a chart's static ChartMember to a dynamic-fanout series. Writes /////. At render time, one rendered series is produced per distinct value of the group expression — the '13 violation types unknown at design time' fan-out. group_field='Type' is a shorthand for =Fields!Type.Value; group_expression accepts any VB.NET. Mutually exclusive. replace=False (default) refuses if the ChartMember already has a ; pass replace=True to overwrite. Operates on the FIRST ChartMember in the hierarchy (v0.4 commit 21 scope; multi-member chains aren't reachable from any v0.4 tool). Returns {chart, series, kind: 'ChartGroup', group_name, expression, changed}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`replace`	No
`chart_name`	Yes
`group_field`	No
`series_name`	Yes
`group_expression`	No

TDQS

A4.4/5.0

Behavior5/5

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

With no annotations, the description fully discloses behavioral traits: the XML writes performed, render-time effect, mutual exclusivity of parameters, replace flag behavior, scope restriction, and return value. This is comprehensive.

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 description is front-loaded with the core purpose and contains detailed, purposeful information. It is somewhat verbose but each sentence adds value, so it earns a high score for structure.

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?

Despite no output schema and 6 parameters, the description covers the essential behavior, constraints, and return value, making it nearly complete for an agent to use correctly.

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

Parameters3/5

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

Schema coverage is 0%, so the description must add meaning. It explains group_field, group_expression, and replace, but does not explain path, chart_name, or series_name, leaving their purpose inferred. Partial compensation.

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 clearly states the tool promotes a static ChartMember to a dynamic-fanout series, using verbs like 'Promote' and specifying the resource. It distinguishes from sibling tools by detailing the specific grouping behavior and XML structure.

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?

The description provides clear context for when to use the tool, including the effect of group_field vs group_expression, replace behavior, and scope limitation. However, it does not explicitly mention alternatives or when not to use it.

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

set_chart_series_typeA

Update and optionally on a named ChartSeries. Combo charts work by setting different types per series in the same chart (e.g. one Bar series and one Line series). v0.4: series_subtype defaults to null/None — omit to PRESERVE the existing subtype. Pass 'Stacked' / 'PercentStacked' / 'Plain' / etc. to override. Pre-v0.4 always wrote 'Plain' by default, silently resetting stacked-bar charts on type-only edits. Returns {chart, series, kind, changed: list[str]} — empty when inputs match existing values.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`chart_name`	Yes
`series_name`	Yes
`series_type`	Yes
`series_subtype`	No

TDQS

A4.6/5.0

Behavior5/5

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

Discloses critical behavioral details: the v0.4 change in default subtype handling (omit preserves, previously reset to 'Plain'), and the return format including 'changed' list.

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?

Concise single paragraph with essential info, but could be slightly better structured with separation of version notes.

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?

Comprehensive for a mutation tool with 5 params: covers parameter behavior, version update, and return value shape despite no output schema.

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?

Adds meaning beyond schema by explaining series_subtype default and valid values (e.g., 'Stacked', 'PercentStacked'), though path, chart_name, series_name are self-explanatory.

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?

Clearly states the tool updates chart series type and subtype, explicitly mentioning combo charts which distinguishes it from sibling tools like set_chart_series_action or set_series_color.

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?

Provides clear context for when to use (updating type/subtype, combo charts) but does not explicitly list alternatives or when not to use.

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

set_chart_titleA

Update /. text can be literal text or an =expression. title_name defaults to 'Default' (the only title the template emits). Returns {chart, title, kind, changed: bool}.

ParametersJSON Schema

Name	Required	Default
`path`	Yes
`text`	Yes
`chart_name`	Yes
`title_name`	No	Default

TDQS

A3.5/5.0

Behavior3/5

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

With no annotations, the description explains that text can be literal or an expression, and title_name defaults to 'Default' as the only title emitted. However, it lacks information on permissions, reversibility, or error behavior, partially informing but not fully comprehensive.

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

Conciseness5/5

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

The description is very concise and front-loaded, with two sentences that efficiently convey purpose and key details without redundancy.

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

Completeness2/5

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

Given no output schema or annotations, the description fails to explain all parameters (path, chart_name), elaborate on return fields (chart, title, kind, changed), or mention error handling or preconditions. Significant information gaps remain.

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

Parameters2/5

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

Schema coverage is 0%, so the description must explain all parameters. It only adds meaning for 'text' (literal or expression) and 'title_name' (default and uniqueness). The required parameters 'path' and 'chart_name' are not described, leaving significant ambiguity.

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 clearly states it updates a chart title or caption, with specific details about text types and title_name default. This distinguishes it from sibling tools like set_chart_axis or set_chart_legend.

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

Usage Guidelines3/5

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

The description provides context about title_name and expression support, but does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. Usage is implied but not contrasted with siblings.

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

set_column_group_sortA

Replace a column-axis group's with a fresh list. Mirrors set_group_sort but refuses up front if group_name is on the row axis (use set_group_sort instead).

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`group_name`	Yes
`tablix_name`	Yes
`sort_expressions`	Yes

TDQS

A3.9/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It mentions the refusal behavior for row-axis groups, which is good. However, it does not disclose other behavioral traits such as whether the operation is destructive (though 'replace' implies it), permissions needed, or error responses. The description provides some transparency but is not thorough.

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

Conciseness5/5

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

The description is two sentences, directly stating the action and the key constraint. No extraneous words, front-loaded with the main purpose.

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

Completeness2/5

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

Given that there are 4 required parameters with no schema descriptions, no output schema, and no annotations, the description should provide more context about parameter roles and operation results. It omits explanations for 'path' and 'tablix_name', and does not mention if editing transactions are needed, leaving gaps for correct invocation.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate. It only implicitly mentions 'group_name' and 'sort_expressions', but does not explain 'path' or 'tablix_name'. The description adds minimal meaning beyond parameter names, failing to compensate for the lack of schema descriptions.

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 clearly states that the tool replaces sort expressions for a column-axis group. It differentiates from the sibling 'set_group_sort' by specifying that it refuses if the group is on the row axis, providing a clear verb and resource.

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

Usage Guidelines5/5

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

The description explicitly states when to use this tool (for column-axis groups) and when not to (if group_name is on row axis, use set_group_sort instead). This provides excellent guidance on alternatives.

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

set_column_group_visibilityA

Set on a column-axis group's TablixMember. Accepts a Hidden expression and an optional ToggleItem (textbox name that toggles expand/collapse). Mirrors set_group_visibility but refuses up front if group_name is on the row axis.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`group_name`	Yes
`tablix_name`	Yes
`toggle_textbox`	No
`visibility_expression`	Yes

TDQS

A3.7/5.0

Behavior3/5

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

The description discloses that it accepts a Hidden expression and optional toggle, and that it refuses if group_name is on row axis. With no annotations, it covers basic behavior but lacks details on side effects, error handling, or prerequisites (e.g., group must exist).

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

Conciseness5/5

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

Two sentences, front-loaded with purpose, and every word adds value. No redundancy or fluff.

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

Completeness2/5

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

Despite no output schema and missing parameter descriptions, the description lacks completeness. It doesn't explain common required parameters, return behavior, or outcomes. An AI agent might not know how to construct path or tablix_name values.

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

Parameters2/5

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

Schema coverage is 0%, so description must compensate. It explains two of five parameters: visibility_expression as 'Hidden expression' and toggle_textbox as 'ToggleItem'. It does not describe path, group_name, or tablix_name, leaving gaps for an AI agent.

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 clearly states that the tool sets visibility on a column-axis group's TablixMember with a Hidden expression and optional toggle. It distinguishes itself from the sibling set_group_visibility by specifying it only works for column-axis groups, preventing misuse.

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 provides explicit guidance: mirrors set_group_visibility but refuses row-axis groups. This tells the agent when to use this vs set_group_visibility. However, it does not mention other related visibility tools like set_detail_row_visibility or set_element_visibility.

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

set_column_widthA

Set on a tablix's body column. column accepts a 0-based integer index OR a textbox name living in any cell of that column (mirrors how set_cell_span / add_subtotal_row address columns). width is an RDL size ('1.5in', '4cm', '80pt'). Idempotent: same width → {changed: false}, no save.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`width`	Yes
`column`	Yes	0-based column index or textbox name in any column cell.
`tablix_name`	Yes

TDQS

A4/5.0

Behavior3/5

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

With no annotations, the description carries full behavioral burden. It discloses idempotency and that setting the same width results in no save. However, it does not mention transaction requirements (e.g., if a transaction must be started first) or error behavior for invalid inputs.

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

Conciseness5/5

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

The description is two sentences, front-loading the core purpose. Every sentence adds value: the first explains the action and column specification, the second adds width format and idempotency. No wasted words.

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

Completeness4/5

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

For a setter tool with 4 parameters and no output schema, the description covers the key parameters (column, width) well. It lacks details on path and tablix_name, and does not describe the return value shape or error cases, but is sufficient for basic usage.

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 low (25%), but the description adds meaningful semantics for column (0-based index or textbox name) and width (RDL size with examples). It does not clarify path or tablix_name, but these are common and somewhat self-explanatory.

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 clearly states the tool sets width on a tablix body column, a specific verb-resource combination. It distinguishes from sibling tools like set_row_height (rows) and set_tablix_size (overall tablix) by targeting a column's width.

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

Usage Guidelines3/5

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

The description implies usage (when you need to change column width) but lacks explicit when-to-use or when-not-to-use guidance. It mentions that column addressing mirrors set_cell_span/add_subtotal_row, giving context but not alternatives or prerequisites.

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

set_conditional_row_colorA

Color every cell of a tablix's detail row based on the value of one of its fields. Builds a Switch(...) expression mapping field values to colors and writes it as BackgroundColor on every detail cell. value_expression is the field reference (e.g. 'Fields!Status.Value' — a leading '=' is accepted). color_map is an ordered dict of value->color (e.g. {"Red":"#FF0000","Yellow":"#FFFF00"}); first match wins. Unmatched values fall back to default_color (default 'Transparent'). When case_sensitive is False (default), wraps the field reference in UCase() and uppercases the keys for case-insensitive matching. Walks the row hierarchy to find the Details leaf — works after add_row_group nests the structure. Replaces any existing BackgroundColor.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`color_map`	Yes	Ordered map of expected values to color strings. First match in declaration order wins.
`tablix_name`	Yes
`default_color`	No		Transparent
`case_sensitive`	No
`value_expression`	Yes	Field reference to switch on, e.g. 'Fields!Status.Value'. Leading '=' optional.

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations provided, the description fully discloses the behavioral traits: it builds a Switch(...) expression, writes BackgroundColor, handles case sensitivity, walks row hierarchy, and replaces existing BackgroundColor. This is comprehensive.

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?

Description is front-loaded with the main purpose, then adds necessary details. Every sentence contributes value, though it could be slightly more concise without losing clarity.

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?

Given the tool's complexity (6 parameters, nested objects, no output schema), the description is complete. It covers how the tool works, what it writes, hierarchy handling, and edge cases like case sensitivity and fallback.

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 only 33%, but the description adds detailed meaning to all parameters: value_expression format, color_map as ordered dict, default_color default, case_sensitive behavior. This compensates well for the schema gaps.

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?

Description clearly states the verb 'color', the resource 'every cell of a tablix's detail row', and the mechanism 'based on the value of one of its fields'. It distinguishes from sibling tools like set_alternating_row_color and style_tablix_row by specifying conditional per-field coloring.

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?

Description provides clear context on when to use this tool: for coloring detail rows based on a field value. It explains behavior like first-match-wins and fallback to default_color. However, it does not explicitly state when not to use it or mention direct alternatives.

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

set_datasource_connectionA

Repoint a DataSource at a Power BI XMLA endpoint. workspace_url accepts a bare workspace name or a full powerbi:// URL; DataProvider is set to SQL (the AS provider id in RDL).

ParametersJSON Schema

Name	Required	Description
`name`	Yes	RDL DataSource Name attribute.
`path`	Yes
`dataset_name`	Yes	PBI semantic model (Initial Catalog).
`workspace_url`	Yes	Workspace name or full powerbi:// XMLA URL.
`integrated_security`	No	Default true. False omits the element.

TDQS

A3.9/5.0

Behavior3/5

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

With no annotations provided, the description carries the full burden. It discloses that the tool sets the DataProvider to SQL and accepts flexible workspace_url formats. However, it does not mention side effects (e.g., overwriting existing connections), required permissions, or whether the operation is reversible. Some behavioral context is given but not comprehensive.

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

Conciseness5/5

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

The description is concise, consisting of two sentences that immediately convey the core purpose and key parameter details. It is front-loaded and every sentence adds value without redundancy.

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

Completeness3/5

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

Given the tool has 5 parameters, no output schema, and no annotations, the description is adequate for the main behavior but leaves gaps. The 'path' parameter is not explained, and there is no information about return values or success indicators. The description covers essential aspects but could be more complete for a mutation tool.

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?

The description adds value beyond the input schema by clarifying that 'workspace_url' accepts both bare workspace names and full URLs, and by specifying that DataProvider is set to SQL. This supplements the schema, which only lists parameter types and minimal descriptions. The parameter 'path' lacks schema description, and the description does not cover it, but overall the added information is helpful.

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 uses the specific verb 'Repoint' and identifies the resource as 'a DataSource at a Power BI XMLA endpoint'. It distinguishes from sibling tools like 'add_data_source' or 'rename_data_source' by focusing on changing the connection endpoint. The mention of URL format and DataProvider adds clarity.

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

Usage Guidelines3/5

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

The description implies when to use this tool (to repoint a datasource to Power BI) but does not provide explicit guidance on when not to use it or mention alternative tools. Usage is inferred rather than clearly stated.

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

set_detail_row_visibilityB

Set on the tablix's Details group, optionally with a ToggleItem textbox name. Use to hide detail rows by expression without restructuring the row hierarchy.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`expression`	Yes
`tablix_name`	Yes
`toggle_textbox`	No

TDQS

B3/5.0

Behavior2/5

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

With no annotations, the description carries full burden. It states the tool sets visibility and optionally uses a toggle, but does not disclose side effects, whether visibility overrides or merges, or any permission requirements. For a mutation tool, this is insufficient.

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

Conciseness5/5

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

The description is exactly two sentences, front-loading the primary action with no redundant or extraneous words. It efficiently communicates the core purpose and optional behavior.

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

Completeness2/5

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

Given the tool has 4 parameters, no annotations, no output schema, and is a mutation, the description is too minimal. It fails to explain critical parameter details or behavioral constraints, leaving significant gaps for an agent to safely use the tool.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate. It explains 'toggle_textbox' and part of 'tablix_name' context, but 'path' and 'expression' are not described. 'Expression' likely expects a boolean but is ambiguous, and 'path' is unclear. The description adds limited value over the raw schema.

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

Purpose4/5

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

The description clearly states it sets visibility on the tablix's Details group with optional toggle, specifying the resource and action. It distinguishes from restructuring row hierarchy but does not explicitly differentiate from sibling visibility tools like set_group_visibility, though the specific mention of 'Details group' provides adequate clarity.

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

Usage Guidelines3/5

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

The description says 'Use to hide detail rows by expression without restructuring the row hierarchy,' implying when to use and when not to, but it does not name alternative tools or provide explicit exclusions. The context is clear but could be more specific.

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

set_document_map_labelA

Set on any named ReportItem (Textbox / Image / Rectangle / Chart / Tablix / etc.). Surfaces in the rendered report's navigable document-map / table-of-contents pane. Pass '' to clear. Idempotent. Returns {element, kind, changed: bool}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`element_name`	Yes
`label_or_expression`	Yes

TDQS

A3.6/5.0

Behavior3/5

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

No annotations are provided, so the description carries the burden. It mentions idempotency and the return object ({element, kind, changed: bool}), but does not describe error behavior (e.g., if element_name doesn't exist) or any side effects. Basic transparency but incomplete.

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 description is two sentences with no redundancy. It front-loads the purpose and adds a note on clearing. Could be slightly more structured by separating return info, but it's efficient.

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

Completeness3/5

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

Given the tool's complexity (3 required params, no output schema), the description clarifies the return format and idempotency but omits details on the 'path' parameter and does not provide an example. Adequate but not fully complete.

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

Parameters3/5

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

The input schema has no parameter descriptions (0% coverage). The description adds meaning for label_or_expression ('Pass '' to clear'), but path and element_name remain unexplained. Partial compensation for missing schema detail.

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 clearly states it sets a DocumentMapLabel on any named ReportItem, which surfaces in the navigable document-map pane. This verb+resource combination is unique among siblings, effectively distinguishing it.

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

Usage Guidelines3/5

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

The description implies usage by stating what it does and that passing '' clears the label, but it lacks explicit guidance on when to use this tool vs. alternatives (e.g., set_textbox_tooltip). No exclusions or prerequisites are mentioned.

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

set_element_visibilityA

Set on any named ReportItem (Tablix, Textbox, Image, Rectangle, Subreport, Chart). For group-level visibility use set_group_visibility; for detail-row use set_detail_row_visibility. toggle_textbox optionally points at a textbox name that toggles expand/collapse.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`element_name`	Yes
`toggle_textbox`	No
`hidden_expression`	Yes

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description must fully disclose behavior. It mentions setting a hidden_expression and an optional toggle, but does not explain what the hidden_expression evaluates to (e.g., true hides, false shows) or any side effects like overwriting. Some behavioral context is given, but incomplete.

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

Conciseness5/5

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

The description is two sentences with no redundant information. It front-loads the primary action and follows with alternatives and an optional feature. Every sentence adds value.

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

Completeness3/5

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

The tool has 4 parameters with no output schema. The description covers the main action and alternatives, but leaves path and element_name unexplained. For a setting tool, more detail on parameter values (especially hidden_expression syntax) would improve completeness.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must explain parameters. It describes hidden_expression and toggle_textbox, but does not explain path or element_name. Only half the parameters are clarified, leaving ambiguity about the required inputs.

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 clearly states that the tool sets visibility on named ReportItems, listing specific item types. It distinguishes from sibling tools by explicitly naming set_group_visibility and set_detail_row_visibility for other cases.

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

Usage Guidelines5/5

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

It provides explicit guidance: for named ReportItem visibility use this tool, for group-level use set_group_visibility, for detail-row use set_detail_row_visibility. Also explains optional toggle_textbox for expand/collapse behavior.

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

set_footer_item_positionA

Move an existing named ReportItem inside to (top, left). Errors if there is no (call set_page_footer first) or no item by that name.

ParametersJSON Schema

Name	Required	Description	Default
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses error conditions (missing footer, missing item) but does not mention side effects, reversibility, or coordinate units. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with an extra clause for error conditions. No fluff, front-loaded with action. Every part adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and moderate complexity, description covers key prerequisites and error states but lacks parameter details and output behavior. Adequate for a simple move operation but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage, yet description only implies top/left as coordinates without defining units or format. Path and name are not explained. The description adds minimal value beyond the schema's property names.

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 uses a specific verb ('Move') and identifies the resource ('existing named ReportItem inside <PageFooter>') with coordinates. It distinguishes from sibling tools like set_header_item_position or set_footer_item_size by targeting position and specifying the container.

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 states prerequisite: call set_page_footer first if no footer exists. Also warns of error if item name is missing. Could mention when to use set_footer_item_size instead, but the guidance is clear and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_footer_item_sizeB

Resize a named item inside . Same shape as set_header_item_size.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`width`	No
`height`	No

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavior. It states the tool resizes but omits details like units, null behavior, side effects, or permissions. This is insufficient for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no redundancy. Every word contributes to understanding the tool's core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, no annotations, and 4 parameters, the description lacks essential context such as return value, error conditions, dimension units, and behavior for null values. A user cannot fully anticipate the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It mentions 'name', 'width', 'height' but adds no detail about parameter meaning, format, or constraints (e.g., what 'path' is). The reference to set_header_item_size is implicit.

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 specifies the action ('Resize'), the target resource ('a named item inside <PageFooter>'), and references a sibling tool ('Same shape as set_header_item_size'), clearly distinguishing it from other tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool over alternatives (e.g., set_footer_item_position) or prerequisites (e.g., item must exist). The sibling reference hints at similarity but doesn't guide selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_group_page_breakA

Set on a tablix group's page-break rule. location ∈ {None, Start, End, StartAndEnd, Between}. Passing 'None' removes the element (the canonical 'no break' shape). Idempotent. Returns {tablix, group, kind: 'Group', location, changed}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`location`	Yes
`group_name`	Yes
`tablix_name`	Yes

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses idempotency, the effect of 'None' (removes element), and the return structure. Could mention preconditions or error behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences that effectively explain the tool's purpose, special behavior, and return value without unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, idempotency, and return format. Lacks details on prerequisites (e.g., group must exist) and doesn't mention potential errors. Acceptable for a setter tool without output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. Only explains the 'location' parameter's enum values; does not describe 'path', 'tablix_name', or 'group_name' beyond their names.

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?

Clearly states it sets the BreakLocation on a tablix group's page-break rule. Distinguishes from sibling tools like set_group_visibility and set_group_sort by specifying the exact function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage through the description of location values and idempotency, but does not provide explicit guidance on when to use this tool versus alternatives like set_keep_together or set_repeat_on_new_page.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_group_sortC

Replace a group's with a fresh list. Each entry is an RDL expression, e.g. =Fields!Region.Value.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`group_name`	Yes
`tablix_name`	Yes
`sort_expressions`	Yes

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description states it 'replaces ... with a fresh list,' implying overwrite behavior, but does not disclose idempotency, error handling, or whether prior expressions are cleared. Minimal behavioral detail beyond the action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with an example, no unnecessary words. Efficiently communicates the core function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has 4 required params, no output schema, no annotations. Description lacks details on parameter roles, return value, and side effects. Not sufficient for complete understanding without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and the description only explains sort_expressions (RDL expressions with example). Other parameters (path, tablix_name, group_name) are not elaborated. Description partially compensates for one param but not the others.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool replaces a group's SortExpressions with a fresh list, using a verb+resource pattern. It gives an example expression, which helps understand the purpose. However, it could specify whether this applies to row or column groups, though sibling tools like set_column_group_sort imply differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The sibling list includes set_column_group_sort, but the description does not mention when to choose one over the other. No context on prerequisites or restrictions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_group_visibilityB

Set on a group's TablixMember. Accepts a Hidden expression and an optional ToggleItem (a textbox name that toggles the group expand/collapse).

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`group_name`	Yes
`tablix_name`	Yes
`toggle_textbox`	No
`visibility_expression`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It states it sets visibility but does not disclose if the operation is destructive, whether it validates the expression, or what side effects occur. It mentions accept parameters but not behavioral outcomes.

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 description is a single, front-loaded sentence that conveys the core action and key parameters efficiently. However, it could benefit from brief structured details for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 parameters, no output schema, and no annotations, the description is insufficient. It omits details on required parameters like path, tablix_name, and group_name, and does not explain the toggle behavior or return value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It explains visibility_expression as a Hidden expression and toggle_textbox as an optional toggle item, adding meaning beyond the schema. However, it does not clarify path, tablix_name, or group_name.

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 clearly states it sets visibility on a group's TablixMember, distinguishing it from sibling tools like set_column_group_visibility or set_detail_row_visibility. It explicitly mentions the Hidden expression and optional ToggleItem, making the action specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance is provided. There is no comparison to alternative visibility tools among siblings. The description does not indicate prerequisites or context needed for invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_header_item_positionA

Move an existing named ReportItem inside to (top, left). Errors if there is no (call set_page_header first) or no item by that name.

ParametersJSON Schema

Name	Required	Description	Default
`top`	Yes
`left`	Yes
`name`	Yes
`path`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description handles the full burden. It discloses error conditions but does not specify behavior like idempotency, coordinate system/units, or whether it overwrites existing position. The description is adequate but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff. The action, resource, and error conditions are front-loaded. Every word contributes value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with 4 params and no output schema, the description covers the main purpose and error cases. However, it omits parameter format details and return value expectations, which would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (no property descriptions), so the description must compensate. It mentions 'top' and 'left' but does not explain their format (e.g., inches, points, string). 'path' and 'name' are not explained at all, leaving ambiguity for an agent.

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 clearly states the action ('move'), the resource ('existing named ReportItem inside <PageHeader>'), and the target coordinates ('top, left'). It distinguishes from sibling tools like set_header_item_size (which sets size) and add_header_item (which adds).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit error conditions: errors if no <PageHeader> (prerequisite: call set_page_header first) or no item by that name. This gives clear when-to-use and when-not-to-use guidance, including a prerequisite action.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_header_item_sizeA

Resize a named item inside . Mirrors set_body_item_size — at least one of width / height; missing fields untouched; idempotent ({changed: false} when nothing differs). Closes the v0.2 parity gap where only the body variant existed.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`width`	No
`height`	No

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries the burden. States idempotency ('{changed: false} when nothing differs') and that missing fields are untouched. However, does not mention error behavior if the named item does not exist, which is a notable gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no unnecessary words. Front-loaded with the main action. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the resize action, idempotency, and relationship to sibling tool. No output schema, but the description provides enough context for typical use. Could add details on parameter formats or error conditions to be fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Description adds meaning for 'width' and 'height' by noting 'at least one' and 'missing fields untouched', but does not explain 'name' or 'path' parameters beyond the schema. With 0% schema description coverage, some gaps remain.

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?

Clearly states the verb 'resize' and the resource 'named item inside <PageHeader>'. Distinguishes from sibling 'set_body_item_size' by noting it mirrors it and closes a parity gap.

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?

Provides context by referencing 'set_body_item_size' and stating 'at least one of width / height'. Implicitly indicates when to use (for header items) and when not (use body variant for body items). Lacks explicit exclusions but is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_image_actionA

Same shape as set_textbox_action but operates on a named . action_type ∈ Hyperlink / Drillthrough / BookmarkLink. Returns {image, kind, action_type, changed}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`image_name`	Yes
`action_type`	Yes
`target_expression`	Yes
`drillthrough_parameters`	No

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, but the description mentions the return object format {image, kind, action_type, changed} and indicates it is analogous to set_textbox_action. However, it does not disclose side effects, permissions, or what 'changed' means, leaving some ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the sibling comparison, and contains no redundant information. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters, no output schema, and no annotations, the description is incomplete. It fails to explain critical parameters like target_expression and drillthrough_parameters, and does not cover error situations or constraints, leaving agents guessing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds almost no meaning beyond the schema; it does not explain the parameters (path, image_name, target_expression, drillthrough_parameters) or their roles, relying on the schema alone. The mention of 'same shape as set_textbox_action' is indirect, and schema coverage is 0%.

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 clearly states it operates on a named Image and sets an action type (Hyperlink/Drillthrough/BookmarkLink), distinguishing it from the sibling set_textbox_action which operates on textboxes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for images by saying 'operates on a named <Image>', but does not explicitly state when to use this tool versus alternatives like set_image_sizing or set_textbox_action, nor does it describe prerequisites or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_image_sizingA

Set / on a named Image. sizing ∈ AutoSize / Fit / FitProportional / Clip. AutoSize renders at native size (box grows to fit); Fit stretches to fill (ignores aspect ratio); FitProportional preserves aspect ratio; Clip renders at native size, clipped to the box. Idempotent: same value → {changed: false}, no save.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`sizing`	Yes
`image_name`	Yes

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Given no annotations, the description carries full burden. It discloses idempotency and return value for same input, but fails to mention that this tool likely requires an active editing transaction (as many sibling set_* tools do). No side effects or permissions are mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose, then enum details, then idempotency. No filler. Each sentence adds distinct value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, enum semantics, idempotency, and minimal return info. However, it omits the editing transaction context (likely needed) and doesn't explain the path parameter or any prerequisites. Given no output schema and 3 params at 0% coverage, it is somewhat incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% so description must compensate. The enum values are well-explained, but path and image_name parameters are not described at all (path is ambiguous). The description adds some value for sizing but not for the other required parameters.

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 clearly states the verb 'Set' on resource 'Image Sizing', enumerates all four sizing options with brief definitions, and distinguishes itself from sibling tools like set_image_action and set_image_source by focusing solely on sizing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the tool name and description, but no explicit guidance is given on when to use this versus alternatives (e.g., set_image_source). The idempotency note adds value but does not help in choosing between tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_image_sourceA

Repoint an existing at a different embedded image entry without delete-and-readd. Sets Source=Embedded and rewrites to embedded_name. Refuses with a clear error if embedded_name isn't in — leaving a dangling reference would render as a broken image. Add the image first via add_embedded_image. Idempotent: same (Source, Value) pair → {changed: false}, no save. Returns {name, kind, changed: bool}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`image_name`	Yes
`embedded_name`	Yes

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses behavioral traits: refusal on dangling reference, idempotency, side effects (sets Source=Embedded, rewrites Value). No annotations provided, so description fully covers transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured and concise: purpose, behavior, error, prerequisite, idempotency, return format. Each sentence adds value.

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?

Covers return format, error cases, prerequisites, and idempotency. No output schema, but description adequately explains results.

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?

Adds meaning beyond schema: explains embedded_name must exist in EmbeddedImages. Schema coverage is 0%, but description does not elaborate on path or image_name beyond names, which are somewhat self-explanatory.

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?

Clearly states purpose: repoint an existing Image to a different embedded image entry. Uses specific verbs (repoint, sets, rewrites) and distinguishes from delete-and-readd.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use, prerequisite (add_embedded_image), error behavior for dangling references, and idempotency. Contrasts with alternative approach.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_keep_togetherA

Set on a named Tablix / Rectangle / Chart / Textbox / Map / Gauge. Tells the renderer 'don't split this across pages if you can help it'. Best-effort — items larger than a page are still split. keep=False removes the element. Refuses for Image / Line / Subreport and other kinds where the RDL XSD doesn't allow it.

ParametersJSON Schema

Name	Required	Description	Default
`keep`	Yes
`name`	Yes
`path`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses key behaviors: the best-effort splitting, the removal on keep=False, and refusal for certain types. This is transparent about limitations and side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (4 sentences) and front-loads the main purpose. Every sentence adds value without fluff, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and low schema coverage, the description covers the primary functionality, supported types, and limitations. It lacks details on parameter formats, but the essential context for using the tool is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only explains the 'keep' parameter (boolean effect). 'name' and 'path' parameters are not described, leaving ambiguity about format or valid values.

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 clearly states it sets the <KeepTogether> property on specific report items (Tablix, Rectangle, etc.), explains the behavior (best-effort), and distinguishes supported vs. unsupported types (Image, Line, Subreport). This differentiates it from siblings like set_keep_with_group.

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?

The description specifies when to use (for supported item types) and when not to (refuses for unsupported types). It also notes the 'best-effort' nature. While it doesn't explicitly compare to alternatives, the exclusions provide clear guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_keep_with_groupA

Set / on the member that wraps the named group. value ∈ {None, Before, After}. Typical use: a column-header row's member with 'After' to glue it to the data rows that follow. value='None' removes the element.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`value`	Yes
`group_name`	Yes
`tablix_name`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavior. It explains that value 'None' removes the element, indicating a destructive action. It does not mention permissions, prerequisites, or side effects. It is adequate but could be more thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences plus a short third. Front-loaded with the action. Every sentence adds value: action, value domain, typical use, and removal effect. No redundant words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple property setter with 4 required params and no output, the description covers purpose, value semantics, and typical use. It lacks details on path format and error conditions, but given the tool's simplicity, it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must add meaning. It explains the value enum (None, Before, After) and their typical effect. However, it does not explain the 'path' parameter format or the roles of 'tablix_name' and 'group_name'. This leaves ambiguity for correct usage.

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?

Description clearly states it sets the KeepWithGroup property on a TablixMember for a named group. The verb 'Set', resource 'TablixMember>/<KeepWithGroup', and context 'member that wraps the named group' are specific. Distinguishes from sibling set_* tools by targeting a specific property.

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?

Provides a typical use case: column-header row's member with 'After' to glue it to data rows. This gives clear context for when to use. However, it does not explicitly state when not to use or mention alternatives like other properties.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_page_footerC

Same as set_page_header, for .

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`height`	No
`print_on_last_page`	No
`print_on_first_page`	No

TDQS

C2.1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior. It only references set_page_header without any details about side effects, permissions, or consequences of using the tool. The agent receives no insight into what changes occur or what requirements exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely short but at the expense of completeness. It is not self-contained and relies on another tool's description. There is no structure or progressive disclosure; it is a single vague sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, no annotations, no output schema, and a complex set of sibling tools, the description is far from complete. It fails to provide essential context for correct usage, making it inadequate for an AI agent to reliably invoke.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides no information about the parameters. Schema coverage is 0%, meaning the description adds no meaning beyond the schema itself. The agent must infer the purpose of path, height, print_on_first_page, and print_on_last_page without any contextual help.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool is equivalent to set_page_header but for PageFooter, which implies it sets properties on a page footer. While it relies on understanding set_page_header, the object is clearly identified, and it distinguishes from siblings by analogy.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or scenarios where this tool is appropriate or not. The description is too brief to offer usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_page_headerB

Create or update : height plus PrintOnFirstPage / PrintOnLastPage flags. All fields optional — only what's passed gets written.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`height`	No
`print_on_last_page`	No
`print_on_first_page`	No

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose behavior. It mentions 'create or update' and partial writes, but omits potential side effects, error conditions, permissions, or idempotency. Inadequate for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no redundancy. Information is front-loaded and every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Missing output schema and low schema coverage. Description does not cover return value, error handling, or prerequisites (e.g., report must be in edit mode). Incomplete for a mutation tool with no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, yet description only lists field names ('height plus PrintOnFirstPage / PrintOnLastPage flags') without adding meaning, types, or constraints. Does not explain how path works or what values height accepts.

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?

Clearly states the verb 'create or update' and the resource 'PageHeader', specifying the fields affected (height, PrintOnFirstPage, PrintOnLastPage). Distinguishes from sibling tools like set_page_footer by targeting the header specifically.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for modifying page header, but does not explicitly compare to alternatives (e.g., set_page_footer, add_header_image). The phrase 'only what's passed gets written' hints at partial updates but lacks when-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_page_orientationA

Set page orientation by swapping PageHeight and PageWidth when the current orientation doesn't match the requested one. Idempotent. Accepts 'Portrait' or 'Landscape'.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`orientation`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses the core behavior: swapping dimensions, idempotency, and accepted values. It implies no-op on match but doesn't detail error states or return values, though adequate for a simple setter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no fluff. The action is front-loaded, and every sentence adds value: mechanism, idempotency, and accepted values.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a low-complexity tool with no output schema or annotations, the description is fairly complete, covering function, safety (idempotent), and inputs. Missing return info and path explanation, but sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It gives meaning to the 'orientation' parameter with accepted values, but 'path' is not explained. Partial compensation leaves ambiguity for path.

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 clearly states the action 'Set page orientation' and the resource 'page orientation', explaining the mechanism of swapping PageHeight and PageWidth. It is distinct from many sibling tools that deal with other properties.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions idempotency and conditionally swapping only when orientation doesn't match, but it does not provide explicit guidance on when to use this tool versus alternatives like set_page_setup or other page-related tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_page_setupB

Update dimensions, margins, and column count on the first ReportSection. All fields are optional — only what's passed gets written. columns=1 strips the element.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`columns`	No
`margin_top`	No
`page_width`	No
`margin_left`	No
`page_height`	No
`margin_right`	No
`margin_bottom`	No

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. It discloses that only passed fields are written and that columns=1 strips the <Columns/> element. However, it does not discuss permissions, destructive effects, or impact on other settings.

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?

Three sentences with front-loaded purpose. No fluff, but could be slightly more structured. Conciseness is good, but at cost of completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters, no output schema, and no annotations, the description is incomplete. It does not explain return values, constraints on values, or behavior for missing parameters. Leaves many gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, yet description only adds meaning for 'columns' parameter. It groups others under 'dimensions and margins' but does not explain individual parameters like margin_top or page_width. More detail needed.

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 clearly states the tool updates page dimensions, margins, and column count on the first ReportSection. The verb 'update' and resource are specific, and it distinguishes itself from sibling tools by focusing on page setup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. It does not mention prerequisites or when not to use it, which is important given the many sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_parameter_available_valuesA

Set or clear on a report parameter. source='static' with a non-empty static_values writes a list of entries (each entry can be a string or {value, label} dict). source='static' with static_values=[] or omitted CLEARS the element entirely (mirrors set_parameter_prompt('') and returns cleared=true). source='query' writes a to a lookup dataset. Replaces any existing block.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`source`	Yes
`query_dataset`	No
`static_values`	No
`query_label_field`	No
`query_value_field`	No

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the burden. It discloses key behaviors: writing ParameterValue entries for static source, clearing when static_values is empty, writing DataSetReference for query source, and replacing any existing ValidValues block.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph that is dense but well-organized. It front-loads the overall purpose and then details three specific cases. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters and no output schema, the description covers the main behaviors thoroughly. It explains both source modes, clearing, and replacement. However, it lacks explicit details on error conditions, prerequisites, or handling of null static_values (only mentions omitted/empty).

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?

With 0% schema description coverage, the description adds essential meaning beyond the schema. It explains how the source parameter determines behavior, the role of static_values, and the concept of query dataset references. It clarifies the implications of empty or omitted static_values.

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 clearly states the action (set or clear <ValidValues> on a report parameter) and distinguishes between static and query sources. It contrasts with sibling tools like set_parameter_default_values and set_parameter_prompt by focusing specifically on available values.

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?

The description implies when to use this tool (to configure valid values) and explains the clearing behavior. It does not explicitly exclude scenarios or name alternatives, but the context of sibling tools makes the purpose clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_parameter_default_valuesA

Set or clear on a report parameter. source='static' with a non-empty static_values writes a list of expressions. source='static' with static_values=[] or omitted CLEARS the element entirely (mirrors set_parameter_prompt('') and returns cleared=true). source='query' writes a with ValueField only (no LabelField — defaults are values, not display strings). Replaces any existing block.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`source`	Yes
`query_dataset`	No
`static_values`	No
`query_value_field`	No

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description thoroughly details behavior for each source type, including clearing behavior and that query mode uses only ValueField. However, it does not disclose side effects, permissions, or error conditions, which would be necessary without 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?

Single paragraph is dense but clear; front-loads purpose. Could be broken into bullet points for readability, but no wasteful sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers main behavior but lacks details on return values (only mentions 'returns cleared=true' for clear case) and prerequisites like editing mode. With no output schema and 6 params, more completeness would be helpful.

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 has 0% description coverage but description adds significant meaning: explains how source, static_values, and query_value_field interact. Common params like name and path are not described but are standard. Compensates well for low schema coverage.

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 clearly states the tool sets or clears the DefaultValue on a report parameter, with detailed behavior for static vs query sources. It distinguishes from sibling tools like set_parameter_prompt.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied but not explicitly stated; no guidance on when to use this tool versus alternatives such as set_parameter_available_values or set_parameter_prompt. No exclusion criteria given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_parameter_layoutA

Author / explicitly. Writes + ; rewrites so each name in parameter_order lands at (row=index // columns, col=index % columns). Strict permutation check (every existing parameter exactly once). rows*columns must be ≥ parameter count. Auto-creates the layout block when absent. Idempotent: same grid + order → no save. Complements reorder_parameters (declaration order) and sync_parameter_layout (gap-filling). Returns {rows, columns, order, kind, changed}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`rows`	Yes
`columns`	Yes
`parameter_order`	Yes

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses writes to NumberOfRows+NumberOfColumns, rewrites CellDefinitions, strict permutation check, auto-creates block, idempotency, and return values.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, each sentence adds value. No wasted words. Structured to explain behavior, constraints, and relationships efficiently.

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?

With 4 parameters, no output schema, and no annotations, description covers behavior, return values, and differentiation. Fully sufficient for correct invocation.

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 0%, but description explains each parameter: path implied, rows/columns counts, and parameter_order with permutation and layout formula. Adds meaning beyond schema types.

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 clearly states it authors ReportParametersLayout/GridLayoutDefinition with specific verb 'Author' and resource. It explains grid layout behavior and distinguishes from sibling tools reorder_parameters and sync_parameter_layout.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly mentions when to use this tool versus alternatives (reorder_parameters for declaration order, sync_parameter_layout for gap-filling). Also notes idempotency and auto-creation of layout block.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_parameter_promptA

Write the text on a ReportParameter. Empty string clears the element entirely; pass a single space ' ' for blank-but-present.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`prompt`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that an empty string clears the element entirely, and a space leaves it blank but present, which is key behavioral information. Without annotations, the description carries the full burden, and it provides useful mutation details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences that are front-loaded and directly communicate the action and special behaviors. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description adequately covers the core operation and prompt behavior, it lacks context on how 'name' and 'path' are used and does not explain the return value or side effects. For a simple setter, it is minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning only for the 'prompt' parameter (empty vs space), but does not explain the 'name' and 'path' parameters. Since schema coverage is 0% and there are three required parameters, the description should compensate more.

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 specifies the verb 'Write' and the resource '<Prompt> text on a ReportParameter', making the action clear. It distinguishes itself from sibling parameter tools by focusing specifically on setting the prompt text.

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?

The description explicitly states when to use an empty string to clear and a single space for blank-but-present, giving clear guidance on input values. However, it does not provide context about when to use this tool versus other parameter-setting siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_parameter_typeA

Set on a ReportParameter. type ∈ {Boolean, DateTime, Integer, Float, String}. Rejects with ValueError if any existing literal default value would be incompatible with the new type — fix defaults first via set_parameter_default_values, then retry.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`type`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Given no annotations, the description discloses the ValueError error behavior for incompatible defaults, which is a key behavioral trait. It does not mention other side effects, but the tool is a simple mutation. The description does not contradict any annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The first sentence states the core purpose, and the second adds an important usage condition. Every sentence is necessary and well-placed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple mutation tool with three required parameters and no output schema, the description covers the action, allowed types, and error handling. It references a sibling tool for a common prerequisite. However, it does not mention whether an editing transaction is required, which is a minor gap given the context of other tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds value for the 'type' parameter by enumerating allowed values, but it does not explain the 'name' and 'path' parameters. With 0% schema description coverage, the description partially compensates but misses the semantics of how to identify the parameter.

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 clearly states the verb (Set), the resource (DataType on ReportParameter), and lists the allowed types. It distinguishes itself from sibling tools like set_parameter_default_values by mentioning that tool explicitly for handling incompatible defaults.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use (setting type), what error to expect (ValueError for incompatible defaults), and what action to take beforehand (use set_parameter_default_values). This clearly differentiates from other parameter-related tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_repeat_on_new_pageB

Set / on the member that wraps the named group. Most common use: repeat a group header row at the top of every page the group spans. Setting repeat=False removes the element (False is default). Returns {tablix, group, kind: 'TablixMember', repeat, changed}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`repeat`	Yes
`group_name`	Yes
`tablix_name`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It mentions that setting repeat=False removes the element and specifies the return object, but omits side effects, permission requirements, error conditions, or the need for an editing transaction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no unnecessary words. Directly conveys the action, common use, and return value. Front-loads the key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 required parameters, no annotations, no output schema, and a complex domain (report tablix member updates), the description is under-specified. Lacks context about the 'path' parameter, the editing transaction requirement, and how this fits with sibling tools like start_editing_transaction.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 4 parameters with 0% description coverage. The tool description does not explain any parameter meanings (e.g., 'path', 'tablix_name', 'group_name', 'repeat'). The return object hints at 'tablix', 'group', and 'repeat', but this is insufficient for correct parameter usage.

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 clearly states the verb 'Set' and the resource 'RepeatOnNewPage' property on a TablixMember, with a specific use case of repeating group header rows. It distinguishes from sibling tools by specifying the context of group header repetition.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides the most common use case but does not explicitly guide when to use this tool versus alternatives like other set_ operations. No exclusions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_row_heightA

Set the Height of the Nth body row (0-indexed) in a tablix. Accepts any RDL size string ('0.25in', '1cm', '12pt').

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`height`	Yes
`row_index`	Yes
`tablix_name`	Yes

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It mentions 0-indexing and accepted RDL size strings, but does not disclose potential side effects, validation rules, or error conditions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no unnecessary words. Key details are front-loaded and every phrase adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-required-param tool with no output schema and no annotations, the description is minimally adequate but fails to explain the path and tablix_name parameters or any return behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It explains row_index (Nth, 0-indexed) and height (RDL size strings), but path and tablix_name remain unexplained, providing only partial parameter semantics.

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 clearly states the action ('Set the Height') and the resource ('Nth body row in a tablix'), distinguishing it from sibling tools like set_column_width or set_tablix_size.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description only states what it does, not when it's appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_series_colorA

Write into a named series's block, overriding the chart palette for just that series. color accepts a named color ('Red'), a hex string ('#FF0000'), or an =expression. Pass '' to clear (series falls back to the palette). Returns {chart, series, kind, changed: bool}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`color`	Yes
`chart_name`	Yes
`series_name`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description covers the core mutation behavior (override palette, clear with empty string) and return value. It lacks details about error cases or prerequisite conditions, but the provided information is sufficient for safe usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loading the action and return value. Every sentence adds value: operation, parameter details, clearing behavior, and return type. No waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the color parameter and the return object, but for a mutation tool with no output schema, it omits details on error handling (e.g., non-existent series) and prerequisites. It is adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must document all parameters. It only describes the 'color' parameter (accepted formats and clearing behavior), leaving 'path', 'chart_name', and 'series_name' unexplained beyond their names. This is insufficient for an agent to infer correct values.

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 clearly states the verb 'Write' and the resource 'a named series's Style block', specifying the effect of overriding the chart palette for just that series. It distinguishes from sibling tools like set_chart_palette and add_chart_series.

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?

The description explains when to use the tool (to override a single series color) and how to clear it (passing ''). It implies usage context but does not explicitly exclude alternatives or mention when not to use, leaving a minor gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_tablix_cornerA

Write the block — the top-left cell of a matrix-shaped tablix that holds the row-axis caption (e.g. 'Type'). Pass text for a literal value OR expression for a VB.NET '=...' formula. Mutually exclusive. Textbox name is deterministic: '_Corner'. Refuses if the tablix has no named column group (the corner is only meaningful in a matrix). Replaces any existing TablixCorner block. Returns {tablix, name, kind: 'TablixCorner', changed}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`text`	No
`expression`	No
`tablix_name`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses replacement of existing TablixCorner, the return including changed status, and the refusal condition. However, it does not discuss permissions, side effects beyond replacement, or error handling for simultaneous text/expression.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at three sentences, front-loaded with purpose, and every sentence provides necessary detail without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, no output schema, and no annotations, the description partially explains parameters and behavior but omits explanations for 'path' and 'tablix_name'. Return value is mentioned, but error handling for mutually exclusive parameters is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It adds meaning for 'text' (literal value) and 'expression' (VB.NET formula), but does not explain 'path' or 'tablix_name', both required. The description fails to describe two of four parameters, leaving significant gaps.

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 clearly states the tool writes a TablixCorner block, specifying it's the top-left cell of a matrix tablix holding a row-axis caption. The verb 'Write' and resource 'TablixCorner' are precise, distinguishing it from sibling tools like set_tablix_size or add_tablix_column.

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?

The description explains to pass text or expression (mutually exclusive), and notes that it refuses if the tablix has no named column group. This provides context on when the tool is applicable, but does not explicitly compare to alternative tools for setting the corner.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_tablix_sizeA

Resize a tablix by writing and / or directly. Each arg independently optional. Use after adding header / footer rows that change the body's natural height — v0.2's positioning tools only cover top/left, not size. Both values are RDL size strings. Returns {tablix, kind, changed: list[str]} — empty list when inputs match existing.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`width`	No
`height`	No

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description bears burden. It discloses that arguments are independently optional, both are RDL size strings, and returns an object with changed list, empty when no change. No mention of side effects but sufficient for a resize operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. Front-loaded with action, then adds context about usage and return value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, parameters, return value, and usage context. Lacks details on permissions or error behavior, but adequate for a simple resize tool.

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 has 0% description coverage. Description explains that width and height are size parameters, optional, and use RDL strings. Does not detail name and path, but those are typical identifiers.

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 clearly states the action 'Resize a tablix' and the method 'writing <Height> and / or <Width> directly'. It distinguishes from sibling positioning tools by noting they only cover top/left, not size.

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?

Provides explicit guidance: 'Use after adding header / footer rows that change the body's natural height'. Compares to positioning tools, but does not explicitly state when not to use or alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_textbox_actionA

Set / to a Hyperlink (URL), Drillthrough (another report + optional parameters), or BookmarkLink (jump within document). target_expression accepts literal text or =expression. drillthrough_parameters is a list of {name, value} dicts wired into /. Idempotent: same action_type + target + parameters → {changed: false}, no save.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`action_type`	Yes
`textbox_name`	Yes
`target_expression`	Yes
`drillthrough_parameters`	No

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses idempotency and the no-save behavior, and explains that target_expression accepts literal or expression. It lacks details on return format and permissions but adequately covers core behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, with the first covering the main functionality and the second adding idempotency. Every sentence is informative with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters, no output schema, and many sibling tools, the description covers the action types and drillthrough parameters but omits explanation of path and textbox_name formats, and does not mention the need for an editing transaction (implied by siblings like start_editing_transaction).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%. The description adds meaning to action_type by listing the three values, explains target_expression format, and describes drillthrough_parameters as a list of name-value dicts. However, path and textbox_name are not explained beyond being used for identification.

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 clearly states it sets a textbox action to three specific types (Hyperlink, Drillthrough, BookmarkLink), using specific verbs and resource names. It distinguishes from sibling tools like set_textbox_value by focusing solely on action modification.

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 explains the three action types and their purposes (URL, drillthrough with parameters, bookmark jump), providing guidance on when to use each. However, it does not compare with sibling tools like set_chart_series_action or mention when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_textbox_runsA

Replace a textbox's content with multiple children for mixed styling within one display — e.g. 'Asset(s): value' with a bold prefix + regular value in a single textbox. Each run is a dict with required 'text' and optional font_family / font_size / font_weight / font_style / color / format / text_decoration. Replaces the entire subtree (single-paragraph in v0.3; multi-paragraph deferred). Round-trip contract: get_textbox.runs[] returns the same shape this tool writes. Idempotent — identical input is a no-op short-circuit. Returns {textbox, kind, runs, changed}. Pass raw text in each run's text — encoding is handled; don't pre-encode XML entities (use & not &, including for the VB.NET string-concat operator).

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`runs`	Yes
`textbox_name`	Yes

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description fully discloses behavioral traits: idempotent with no-op short-circuit, replaces entire Paragraphs subtree (with version notes), round-trip contract, return fields, and encoding instructions (do not pre-encode).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose, uses a clear example, and packs essential behavioral notes into 3-4 concise sentences without waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (nested runs parameter) and lack of annotations/output schema, the description is impressively complete: it covers idempotency, version constraints, encoding, and return shape. A minor gap is missing details on parameter value formats.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description adds meaning by detailing the 'runs' parameter structure (required text, optional styling fields) and noting to pass raw text. However, it lacks specific formats for fields like color and format (e.g., hex, named).

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 states a specific verb ('Replace') and resource ('textbox content with multiple runs'), gives a concrete example with mixed styling, and distinguishes from sibling tools like set_textbox_value by focusing on multi-run content.

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?

The description explains when to use this tool (mixed styling within one display) and mentions the round-trip contract with get_textbox. However, it does not explicitly list when not to use it or contrast with alternatives like set_textbox_value.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_textbox_styleA

Set styling on a named Textbox. Properties route to the right nested Style node automatically: background_color, border_*, vertical_align, padding_*, writing_mode go on Textbox/Style; text_align on Paragraph/Style; font_*, color, format on TextRun/Style; can_grow / can_shrink go DIRECTLY on Textbox (not inside Style). All fields optional — only what's passed gets written. Cell-level styling: every tablix cell is a Textbox with a unique name, so use this tool with the cell's textbox name (e.g. 'HeaderAmount').

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`color`	No	Text color — '#RRGGBB' or named.
`format`	No	Number/date format (e.g. '#,0.00', 'C2', 'd').
`can_grow`	No	Allow textbox to grow vertically when content exceeds the height. Direct Textbox child, not Style.
`font_size`	No	RDL size, e.g. '11pt'.
`can_shrink`	No	Allow textbox to shrink when content is shorter than the height. Direct Textbox child, not Style.
`text_align`	No	Left \| Center \| Right \| Justify \| General.
`font_family`	No
`font_weight`	No	Normal \| Bold \| Lighter \| ... or numeric.
`padding_top`	No	RDL size (e.g. '2pt', '0.05in').
`border_color`	No
`border_style`	No	None \| Solid \| Dotted \| Dashed \| Double.
`border_width`	No
`padding_left`	No
`textbox_name`	Yes
`writing_mode`	No	Horizontal \| Vertical \| Rotate270 — text orientation. Useful for narrow column headers.
`padding_right`	No
`padding_bottom`	No
`vertical_align`	No	Top \| Middle \| Bottom.
`background_color`	No

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries full burden. It discloses that properties route to different style nodes and that can_grow/can_shrink go directly on Textbox. States all fields optional. Missing details on permissions or side effects, but adequate for a styling tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Efficient, well-structured paragraph. Front-loaded with main action, followed by routing details, optionality, and usage example. No waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 20 parameters, 2 required, and no output schema, the description covers routing and usage context well. Lacks mention of return value, but as a setter, that's less critical. Adequate for the tool's complexity.

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 55%, but description adds valuable info on property routing ('background_color goes on Textbox/Style', etc.) and clarifies textbox naming for tablix cells. Supplements schema definitions meaningfully.

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?

Description clearly states 'Set styling on a named Textbox' with specific verb and resource. It details property routing to nested style nodes, distinguishing it from siblings like set_textbox_value or set_textbox_action.

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?

Provides clear context: cell-level styling using unique textbox names, and emphasizes that only passed fields are written. However, lacks explicit guidance on when not to use this tool versus alternatives like set_textbox_style_bulk.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_textbox_style_bulkA

Apply the same style kwargs to every named textbox in one call. Same kwarg surface as set_textbox_style. Missing names land in skipped rather than raising. Returns {textboxes, skipped, changed} where changed is the union of sub-paths affected across all textboxes. Pair with find_textboxes_by_style to discover names by current style.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`color`	No
`format`	No
`can_grow`	No
`font_size`	No
`can_shrink`	No
`text_align`	No
`font_family`	No
`font_weight`	No
`padding_top`	No
`border_color`	No
`border_style`	No
`border_width`	No
`padding_left`	No
`writing_mode`	No
`padding_right`	No
`textbox_names`	Yes
`padding_bottom`	No
`vertical_align`	No
`background_color`	No

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses key behaviors: same kwarg surface, skipped names, return format with union of changed sub-paths. Lacks mention of atomicity or partial failure handling, but overall transparent for a bulk operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose, no redundancy. Efficiently conveys key points.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 20 parameters and no output schema, the description is adequate but not exhaustive. It explains return value and skipped behavior but does not detail parameter effects or default behaviors (e.g., null meaning). References set_textbox_style for surface, which is helpful if that tool is well-documented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 20 parameters with 0% description coverage. Description merely references set_textbox_style's kwarg surface without listing or explaining any parameters. Agent would need external knowledge of that sibling tool's parameter semantics.

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 clearly states the tool applies the same style to multiple textboxes, distinguishing it from the single-textbox sibling set_textbox_style. It also mentions the return structure and pairing with find_textboxes_by_style.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use (bulk apply) vs single-textbox alternative, and describes behavior for missing names (skipped, not error). Also suggests pairing with find_textboxes_by_style for discovery.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_textbox_tooltipA

Set /. Literal text or =expression. Pass '' to clear. Idempotent. Returns {textbox, kind, changed: bool}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`textbox_name`	Yes
`text_or_expression`	Yes

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses idempotency, the ability to clear the tooltip by passing an empty string, and the return value structure. However, it does not mention potential side effects, authorization needs, or the requirement of an editing transaction, which is common for such modification tools.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two short sentences. The key action is front-loaded ('Set <Textbox>/<ToolTip>'), and every phrase adds value: literal/expression, clearing, idempotency, and return value. There is no superfluous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with three required parameters and no output schema, the description covers essential behaviors: setting, clearing, idempotence, and return format. However, it lacks context about the editing transaction requirement and does not clarify the exact meaning of 'path' (report path or file path?). This is adequate but not fully complete for all use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema coverage is 0%, so the description must compensate. It adds meaning for the 'text_or_expression' parameter by specifying it can be literal text or an expression with a leading '=' and that passing '' clears. However, it does not explain the 'path' or 'textbox_name' parameters, relying on context. This partial compensation brings the score to 3.

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 clearly states the verb 'Set', the resource 'Textbox/ToolTip', and specifies that it can accept literal text or expressions starting with '='. It also clarifies that passing an empty string clears the tooltip. This is very specific and distinct from other sibling tools, though it doesn't explicitly differentiate from set_textbox_value or set_textbox_runs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites like being in an editing transaction, nor does it contrast with other textbox-setting tools. The only usage hint is the mention of idempotency, which is a behavioral trait rather than usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_textbox_valueA

Replace the text content of a single-run textbox. value can be raw text or an =expression. Use this for the everyday 'change the textbox content' case (swap a literal label, update a stale parameter reference, replace a broken aggregate). Refuses with a redirect to set_textbox_runs when the textbox has multiple text runs (multi-run content needs the rich-text editor). Idempotent: identical value → {changed: false} no-op. Returns {textbox, kind, changed}. Pass raw text — encoding is handled; don't pre-encode XML entities (use & not &, including for the VB.NET string-concat operator in expressions).

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`value`	Yes
`textbox_name`	Yes

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries full burden. Discloses idempotency (returns {changed: false} no-op), return structure ({textbox, kind, changed}), error behavior (refuses for multi-run), and encoding details (don't pre-encode). Covers important behavioral traits beyond basic mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but well-structured: primary action, use cases, edge case, idempotency, return type, encoding note. Every sentence adds value with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers behavior, return, encoding, and error handling. Missing clarification of path and textbox_name parameters, which may be assumed but not explicitly defined. With no output schema, return shape is stated. Good overall but slight gap in parameter description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% (no parameter descriptions). Description adds meaning for value (raw text or =expression, encoding guidance) but does not explain path or textbox_name. Provides partial compensation; adequately documents the most nuanced parameter.

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 clearly states the tool replaces text content of a single-run textbox. It uses specific verbs ('Replace') and resources ('text content of a single-run textbox'), and distinguishes from the sibling tool set_textbox_runs for multi-run cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance with concrete examples (swap label, update parameter, replace aggregate). States when not to use (multiple runs) and redirects to set_textbox_runs. Also gives encoding usage instruction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_editing_transactionA

Open the report and start an editing transaction. Returns {transaction_id, path, expires_at}. Pass transaction_id to subsequent edit tools to mutate the live in-memory tree WITHOUT touching disk between calls — eliminates the per-edit parse+serialize round-trip. The transaction times out after PBIRB_MCP_TRANSACTION_TIMEOUT_S seconds (default 600); call commit_editing_transaction to flush or cancel_editing_transaction to discard. Refuses if an active transaction already owns this path.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the transaction timeout, the refusal condition for overlapping transactions, and the effect of eliminating disk writes. It could mention any authentication or permission requirements, but overall it is transparent about behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded. Every sentence adds value: purpose, return value, benefit, timeout, refusal condition. No unnecessary words.

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?

Given the tool's complexity, lack of output schema, and the presence of only one parameter, the description is complete. It explains return values, timeout, and refusal condition. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter (path) has full schema description coverage. The description does not add additional semantics beyond the schema, so baseline score of 3 is appropriate.

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 clearly states that the tool opens a report and starts an editing transaction, specifying the return value and the benefit of eliminating per-edit parse+serialize round-trips. This distinguishes it from sibling tools like commit and cancel.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool (for editing without touching disk between calls) and when not to (refuses if an active transaction exists). It also instructs to call commit or cancel to finalize the transaction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

style_tablix_rowA

Apply the same style kwargs to every cell in a tablix row in ONE call. Replaces the 12-individual-set_textbox_style-calls-per-row pattern. row accepts: integer (0-based body row index), 'header' (first leaf with KeepWithGroup=After — the column header row), 'details' (the Details leaf row), 'header' (header row of a named row group), 'footer' (footer row when present, e.g. after add_subtotal_row). Same style kwargs as set_textbox_style (font*, color, background_color, border, padding_, writing_mode, can_grow, can_shrink, etc.). Delegates writes to set_textbox_style_bulk. Returns {tablix, row, row_index, kind, cells, changed, skipped}.

ParametersJSON Schema

Name	Required	Description
`row`	Yes	Integer index, or one of: 'header', 'details', '<group>_header', '<group>_footer'.
`path`	Yes
`color`	No
`format`	No
`can_grow`	No
`font_size`	No
`can_shrink`	No
`text_align`	No
`font_family`	No
`font_weight`	No
`padding_top`	No
`tablix_name`	Yes
`border_color`	No
`border_style`	No
`border_width`	No
`padding_left`	No
`writing_mode`	No
`padding_right`	No
`padding_bottom`	No
`vertical_align`	No
`background_color`	No

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it explains that style is applied to every cell, lists row specifiers (integer, 'header', 'details', etc.), mentions delegation to set_textbox_style_bulk, and specifies the return value structure. It lacks details on error behavior or permissions, but for a style application tool, this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and concise. Each sentence adds value: purpose, replacement pattern, row parameter details, style kwargs, delegation, and return value. No unnecessary words, and the information is front-loaded with the primary purpose first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (21 parameters, row specifiers, delegation), the description covers the key aspects: purpose, row types, style kwargs, and return. It does not detail each parameter but references set_textbox_style. The return value is described despite no output schema. Overall, it provides enough context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is very low (5%), putting burden on the description. The description lists many style kwargs in parentheses and explains row values, but does not individually define each parameter. It references set_textbox_style for full details, which helps but is not exhaustive. The description compensates partially but could be more complete.

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 clearly states the tool's purpose: 'Apply the same style kwargs to every cell in a tablix row in ONE call.' It specifies the verb (apply) and resource (tablix row), and explicitly distinguishes it from the pattern of making 12 individual set_textbox_style calls, helping the agent know when to choose this tool.

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?

The description provides clear usage context by stating the tool replaces a multi-call pattern (12-individual-set_textbox_style-calls-per-row). It details the row parameter options and refers to set_textbox_style for style kwargs. However, it does not explicitly state when not to use it or mention alternatives for styling individual cells, but the context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

sum_whereA

Emit =Sum(IIf(, , 0)) — the SSRS conditional-sum idiom. Both args are expression bodies (no leading '=').

ParametersJSON Schema

Name	Required	Description	Default
`condition`	Yes	RDL expression body, e.g. 'Fields!Status.Value = "Active"'.
`field_expression`	Yes	Value to sum, e.g. 'Fields!Amount.Value'.

TDQS

A4.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explains that the tool emits an expression but does not mention side effects, permissions, or return format. It adds a behavioral detail that arguments are expression bodies without leading '=', which is helpful but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, consisting of two short sentences. It front-loads the key formula and immediately provides critical formatting guidance. Every sentence adds value with no redundant information.

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?

Given the tool's simplicity (2 parameters, no output schema, no annotations), the description is complete. It fully explains what the tool does, how to construct the expression, and the exact format of inputs. No additional information is needed for an agent to correctly invoke this tool.

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?

The description adds significant meaning beyond the input schema. It explains that both parameters are expression bodies without leading '=' and provides concrete examples: 'e.g., ''Fields!Status.Value = "Active"''' for condition and 'e.g., ''Fields!Amount.Value''' for field_expression. This clarifies the expected format and usage, despite 100% schema coverage.

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 clearly states the tool emits the SSRS conditional-sum idiom '=Sum(IIf(<condition>, <field_expression>, 0))', specifying the verb 'Emit' and the exact expression pattern. This distinguishes it from siblings like 'count_where' which handles a different aggregate.

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?

The description includes a usage note that 'Both args are expression bodies (no leading '='),' which helps the agent format inputs correctly. While it doesn't explicitly state when to use this tool versus alternatives, the context of 'SSRS conditional-sum idiom' implies it is for conditional summation in SSRS reports. No exclusion criteria or alternative tools are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

sync_parameter_layoutA

Bring // into sync with . Drops cells whose ParameterName no longer exists; appends cells for parameters that have no entry, placed at the next free (row, col) slot. add_parameter / remove_parameter / rename_parameter call this internally; the standalone tool is for repairing legacy reports authored before v0.3.0 where the layout drifted. No-op when the report has no . Returns {added, removed}.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses key behaviors: dropping cells for missing parameters, appending at next free slot, and returning a {added, removed} summary. It also explains the internal usage by other tools. Without annotations, this provides sufficient transparency, though it could mention if the operation modifies the report file directly.

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 description is well-structured: first sentence states purpose, then details, usage guidance, no-op condition, and return value. It is slightly verbose but packs necessary information without unnecessary fluff.

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 specialized tool with one parameter, the description covers purpose, behavior, use case, and return value. It is complete and answers likely questions an agent might have about when and why to use it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with only one parameter (path) described. The description does not add extra meaning beyond the schema's description, so baseline score of 3 is appropriate.

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 uses specific verbs like 'bring into sync', 'drops', 'appends', clearly stating the tool's function. It also distinguishes from sibling tools like add_parameter by noting they call this internally, clarifying its specific role.

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?

The description explicitly states the primary use case (repairing legacy reports before v0.3.0) and notes the no-op condition. However, it does not explicitly state when not to use it, though it is implied that it's not needed for normal operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_dataset_queryA

Replace the DAX command text of a named dataset. The full DAX expression is accepted verbatim; empty bodies are rejected. Optional alias_strategy='preserve_field_names' positionally rewrites cells to the new DAX columns while keeping existing identifiers — so Fields!X.Value references in expressions keep resolving.

ParametersJSON Schema

Name	Required	Description
`path`	Yes
`dax_body`	Yes	Full DAX (e.g. EVALUATE TOPN(10, 'Sales')).
`dataset_name`	Yes
`alias_strategy`	No	When 'preserve_field_names', positionally remap <DataField> cells to the new DAX column list.

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that empty bodies are rejected and explains alias_strategy behavior, but does not mention whether the tool is destructive, requires specific permissions, or if the dataset must exist. Lacks full safety/permission context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two concise sentences. The first sentence states the main action upfront, and the second elaborates on the optional strategy. No extraneous text, effectively front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description does not mention return values or success indicators. It also lacks prerequisites (e.g., dataset must exist) and potential side effects. Adequate but not fully complete given the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50% (2 of 4 parameters have descriptions). The tool description adds value for dax_body (empty bodies rejected) and alias_strategy (positional rewiring), but does not clarify path or dataset_name parameters. The description partially compensates for documentation gaps.

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 clearly states 'Replace the DAX command text of a named dataset', using a specific verb and resource. It distinguishes from sibling tools like update_query_parameter which modify query parameters rather than the DAX command itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for replacing DAX queries but does not explicitly specify when to use this tool versus alternatives like update_query_parameter or add_dataset_field. No exclusions or alternative recommendations are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_parameter_advancedA

Toggle the four boolean flags on a report parameter: multi_value, hidden, allow_null (writes ), allow_blank. Each is independently optional. With no flags passed it's a no-op. Cascading parameters are NOT a flag — use set_parameter_available_values(source='query') + add_query_parameter on the lookup dataset to wire a dependency on another parameter.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`hidden`	No
`allow_null`	No
`allow_blank`	No
`multi_value`	No

TDQS

A4.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that the tool toggles boolean flags, that allow_null writes <Nullable>, and that no flags results in a no-op. It does not mention prerequisites like needing an editing transaction or required permissions, but the behavioral details given are sufficient for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences covering all essential details. The first sentence lists the flags; the second clarifies no-op behavior and distinguishes from cascading parameters. No unnecessary words.

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?

Given the moderate complexity (four boolean flags), no output schema, and no annotations, the description is complete enough. It explains all parameters, provides usage guidelines, and addresses common confusion about cascading parameters. An agent can confidently use this tool based on the description alone.

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?

The description adds significant meaning beyond the raw schema, which has 0% description coverage. It explains each boolean flag's purpose (e.g., allow_null writes <Nullable>) and mentions that name and path are required. This compensates fully for the schema's lack of descriptions.

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 clearly states the tool toggles four specific boolean flags (multi_value, hidden, allow_null, allow_blank) on a report parameter. It lists each flag and distinguishes itself from sibling tools by explicitly noting that cascading parameters are not a flag and directing to alternative tools, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Each is independently optional. With no flags passed it's a no-op.' This provides clear guidance on when to use the tool (to toggle these flags) and when not to (for cascading parameters), naming specific alternative tools. This effectively helps in tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_query_parameterB

Change the value expression of an existing query parameter. Same PBIDATASET @-prefix normalisation as add_query_parameter applies on lookup; legacy Name='@X' parameters that already exist on disk are addressable via either @X or X.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`path`	Yes
`dataset_name`	Yes
`force_at_prefix`	No
`value_expression`	Yes

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Provides useful behavioral context about @-prefix normalization and legacy name addressing, but does not disclose potential side effects, required authorizations, or behavior on non-existent parameters. Given no annotations, the description partially compensates but remains incomplete.

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?

Very concise with two sentences and no wasted words. Could be slightly improved by front-loading the most critical information, but structure is adequate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 5 parameters, no output schema, and no annotations, the description fails to cover the parameter semantics or return behavior. The normalization note is helpful but does not sufficiently complete the tool's context for safe and correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain parameters. It only clarifies the 'name' parameter's addressing and 'value_expression' role. Other critical parameters (path, dataset_name, force_at_prefix) are not explained, leaving the agent without guidance.

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?

Clearly states the verb 'Change' and resource 'the value expression of an existing query parameter'. Distinguishes from sibling tools like add_query_parameter, remove_query_parameter, and rename_parameter by specifying exactly what is updated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for updating value expressions of existing parameters, but lacks explicit guidance on when to use this versus alternatives like remove+add or other set_parameter_* tools. No exclusions or prerequisites mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_reportA

Run schema/structural validation against an .rdl. Returns {valid, errors, xsd_used}. Structural checks always run (root element + required top-level sections). The Microsoft RDL 2016/01 XSD is bundled by default since v0.3.1 — when it's loaded, xsd_used is True and the schema-conformance bug class Power BI Report Builder rejects on load gets caught here. If the bundled XSD is missing (source-build without package-data) a {severity:warning, rule:'xsd-not-bundled'} issue surfaces instead of silent skip. Each issue is {severity, rule, location, message, suggestion?}; valid is True iff no severity='error' issue.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

A4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility. It thoroughly discloses behavioral traits: structural checks always run, XSD bundling details, edge cases when XSD is missing, and the exact output format with issue structure. This level of detail fully informs an agent about what to expect.

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 description is relatively long but each sentence adds value, explaining output, edge cases, and error reporting. The main purpose is front-loaded, and there is no superfluous text. It could be slightly more streamlined, but overall efficient.

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?

Given the tool's simplicity (one parameter, no output schema), the description is comprehensive. It explains the return structure, validity condition, and important edge cases (XSD missing). An agent has all necessary information to correctly invoke and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100% for the single parameter 'path', which is already described in the schema as 'Absolute path to the .rdl file to read.' The description adds no additional meaning beyond the schema, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs schema/structural validation on .rdl files, using a specific verb and resource. However, it does not explicitly differentiate from sibling tools like 'lint_report' or 'verify_report', which may perform overlapping checks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies validation of .rdl files but does not provide explicit guidance on when to use this tool over alternatives, such as for pre-deployment checks vs. ongoing linting. No when-not-to-use or alternative recommendations are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verify_reportA

One-shot static check: union of validate_report and lint_report. Returns {valid, issues, xsd_used} where valid is True iff no issue has severity='error'. Warnings (including 'xsd-not-bundled' when the schema file is missing) don't invalidate the report. Use this as the single 'is the report OK?' tool, or set PBIRB_MCP_AUTO_VERIFY=1 to have it run after every mutating call.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to the .rdl file to read.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It explains the return fields, the condition for valid (no error severity), and that warnings like 'xsd-not-bundled' don't invalidate. It implies read-only via 'static check', though not explicitly stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph that efficiently covers purpose, return value, behavior, and usage guidance. Front-loaded with the key verb and resource.

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?

Despite no output schema, the description explains the return structure in detail. It provides sufficient context for an agent to use the tool correctly, especially given the sibling tools it supersedes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'path' is fully described in the input schema with 100% coverage. The tool description does not add additional semantic information beyond the schema.

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 clearly states the tool is a one-shot static check that combines validate_report and lint_report, and specifies its return structure. This distinguishes it from its sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly positions this as the single 'is the report OK?' tool and mentions the environment variable for auto-running after mutating calls, providing clear when-to-use and alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

143 tool updatesv0.4.1Jun 28, 2026
- First observedadd_body_image
- First observedadd_body_textbox
- First observedadd_calculated_field
- First observedadd_chart_series
- First observedadd_column_group
- First observedadd_data_source
- First observedadd_dataset_field
- First observedadd_dataset_filter
- First observedadd_embedded_image
- First observedadd_footer_image
- First observedadd_footer_textbox
- First observedadd_header_image
- First observedadd_header_textbox
- First observedadd_line
- First observedadd_list
- First observedadd_parameter
- First observedadd_query_parameter
- First observedadd_rectangle
- First observedadd_row_group
- First observedadd_static_column
- First observedadd_static_row
- First observedadd_subtotal_column
- First observedadd_subtotal_row
- First observedadd_tablix_column
- First observedadd_tablix_filter
- First observedapply_edits
- First observedbackup_report
- First observedcancel_editing_transaction
- First observedcommit_editing_transaction
- First observedconvert_to_matrix
- First observedcount_where
- First observedcreate_report
- First observeddescribe_report
- First observeddry_run_edit
- First observedduplicate_report
- First observedfind_textbox_by_value
- First observedfind_textboxes_by_style
- First observedget_chart
- First observedget_data_source
- First observedget_dataset
- First observedget_datasets
- First observedget_embedded_image_data
- First observedget_expression_reference
- First observedget_image
- First observedget_parameters
- First observedget_rectangle
- First observedget_tablixes
- First observedget_textbox
- First observediif_format
- First observedinsert_chart_from_template
- First observedinsert_tablix_from_template
- First observedlint_report
- First observedlist_body_items
- First observedlist_data_sources
- First observedlist_dataset_filters
- First observedlist_embedded_images
- First observedlist_footer_items
- First observedlist_header_items
- First observedlist_tablix_filters
- First observedraw_xml_replace
- First observedraw_xml_view
- First observedrefresh_dataset_fields
- First observedremove_body_item
- First observedremove_calculated_field
- First observedremove_chart_series
- First observedremove_column_group
- First observedremove_data_source
- First observedremove_dataset_field
- First observedremove_dataset_filter
- First observedremove_embedded_image
- First observedremove_footer_item
- First observedremove_header_item
- First observedremove_parameter
- First observedremove_query_parameter
- First observedremove_row_group
- First observedremove_tablix_column
- First observedremove_tablix_filter
- First observedrename_data_source
- First observedrename_parameter
- First observedreorder_parameters
- First observedrestore_from_backup
- First observedset_alternating_row_color
- First observedset_body_item_position
- First observedset_body_item_size
- First observedset_body_size
- First observedset_cell_span
- First observedset_chart_axis
- First observedset_chart_data_labels
- First observedset_chart_legend
- First observedset_chart_palette
- First observedset_chart_series_action
- First observedset_chart_series_grouping
- First observedset_chart_series_type
- First observedset_chart_title
- First observedset_column_group_sort
- First observedset_column_group_visibility
- First observedset_column_width
- First observedset_conditional_row_color
- First observedset_datasource_connection
- First observedset_detail_row_visibility
- First observedset_document_map_label
- First observedset_element_visibility
- First observedset_footer_item_position
- First observedset_footer_item_size
- First observedset_group_page_break
- First observedset_group_sort
- First observedset_group_visibility
- First observedset_header_item_position
- First observedset_header_item_size
- First observedset_image_action
- First observedset_image_sizing
- First observedset_image_source
- First observedset_keep_together
- First observedset_keep_with_group
- First observedset_page_footer
- First observedset_page_header
- First observedset_page_orientation
- First observedset_page_setup
- First observedset_parameter_available_values
- First observedset_parameter_default_values
- First observedset_parameter_layout
- First observedset_parameter_prompt
- First observedset_parameter_type
- First observedset_repeat_on_new_page
- First observedset_row_height
- First observedset_series_color
- First observedset_tablix_corner
- First observedset_tablix_size
- First observedset_textbox_action
- First observedset_textbox_runs
- First observedset_textbox_style
- First observedset_textbox_style_bulk
- First observedset_textbox_tooltip
- First observedset_textbox_value
- First observedstart_editing_transaction
- First observedstyle_tablix_row
- First observedsum_where
- First observedsync_parameter_layout
- First observedupdate_dataset_query
- First observedupdate_parameter_advanced
- First observedupdate_query_parameter
- First observedvalidate_report
- First observedverify_report

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-06-28 17:25 across 143 tools

Disambiguation5/5

Every tool has a clearly distinct purpose with detailed descriptions, ranging from adding, removing, setting, getting, listing, and updating various report elements. There is no ambiguity; each tool targets a specific report component or operation.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_body_image, set_textbox_value, list_data_sources). No mixing of conventions or styles.

Tool Count1/5

143 tools is an extreme mismatch for typical MCP servers, even considering the complex domain of RDL report editing. The count far exceeds the '25+' threshold for 'too many', making it difficult for agents to navigate and select appropriately.

Completeness5/5

The tool set covers the full lifecycle of RDL report creation and manipulation: CRUD for all major elements (data sources, datasets, parameters, tablixes, charts, images, etc.), plus validation, linting, backup, and editing transactions. No obvious gaps.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

CData Connect AIOAuth
com.cdata
Cloud-hosted MCP server for secure AI access to enterprise data sources via CData Connect AI.
Databases RAG Systems Cloud Platforms
2
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
LemonadoOAuth
io.github.lemonadolabs
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Marketing Research & Data Databases
3
docs A
com.stimulsoft
Stimulsoft Reports & Dashboards docs MCP server. Semantic search for all platforms.
Documentation Access Search Developer Tools
22

Related MCP Servers

Power BI Report MCP Server
Data Visualization Developer Tools
jonathan-pap
A
license
B
quality
D
maintenance
Build Power BI reports with natural language through an MCP server that connects AI assistants to Power BI's PBIR file format for creating pages, visuals, themes, and filters locally.
Updated 4 months ago (2026-05-14 16:57 UTC)
57
19
MIT
Power BI MCP for Claude
Cloud Platforms Databases Data Visualization
robertoamoreno
A
license
Not graded
quality
C
maintenance
MCP server for Microsoft Power BI and Fabric, enabling Claude to discover workspaces, semantic models, generate and execute DAX queries, and retrieve report metadata via device-code authentication.
Updated a month ago (2026-08-06 18:44 UTC)
20 npm
1
MIT
pbix-mcp
Data Visualization Databases Developer Tools
d0nk3yhm
A
license
Not graded
quality
A
maintenance
MCP server for creating, editing, and evaluating Power BI (.pbix/.pbit) files without Power BI Desktop. Supports 101 tools including report creation, data sources, DAX measures, and file manipulation.
Updated 15 days ago (2026-08-31 23:36 UTC)
17
MIT
Fabric Report MCP
Cloud Platforms Developer Tools
data-goblin
F
license
Not graded
quality
D
maintenance
MCP server for managing Microsoft Fabric Reports with lifecycle management, filtering, and content manipulation.
Updated a year ago (2025-08-21 16:40 UTC)
8
-