Skip to main content
Glama
pietrodileo

IRIS MCP Blueprint

by pietrodileo
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

IRIS MCP Blueprint

⚠️ This repository is an example, not a finished product. It's a blueprint showing how to build an MCP server for InterSystems IRIS that performs operations across several tool categories: SQL, Globals, Class methods, Atelier API, and Interoperability (see src/iris_mcp_blueprint/tools/), plus a handful of reusable prompts and resources. It is not meant to be a one-size-fits-all MCP server for every IRIS workload. Use it as a starting point: clone it, keep what you need, drop what you don't, and adapt the tools, prompts, and resources to your own IRIS application (namespaces, classes, productions, security model, business rules, and so on). The ObjectScript demo under src/MCPTest/ is only there to give the included tools/prompts something to work against.

A FastMCP server that exposes tools, prompts, and resources to work with InterSystems IRIS with any MCP-compatible client (Cursor, Claude Desktop, and others). The Python package under src/iris_mcp_blueprint/ connects to IRIS over the Native SDK and wraps the operations you tend to repeat by hand — running SQL, poking at globals, searching code through the Atelier API, driving an Interoperability production, calling class methods, and so on. The ObjectScript classes in src/MCPTest/ (including MCPTest.BP.QueryService) are there as a concrete target so the tools and the guided prompts have something realistic to operate on.

Prerequisites

Tool

Why it’s needed

Source / version pin in this repo

Python 3.12

Runtime that satisfies requires-python = ">=3.12" in pyproject.toml

.python-version ⇒ 3.12 (read by uv to provision the venv)

uv ≥ 0.5

Installs deps from pyproject.toml + uv.lock, runs the CLI (uv run) and remote builds (uvx)

Versions older than 0.5 may not understand the lockfile or uv init --package

Docker with docker compose v2

Runs the IRIS database container described by docker-compose.yml

Image: intersystems/iris-community:latest-cd (see Dockerfile)

Git

Cloning this repo (and any uvx --from git+... install of remote forks)

—

MCP-compatible client (at runtime)

Drives the prompts and tools

Cursor, Claude Desktop, or anything that speaks MCP over stdio / SSE

Notes:

  • You don’t need to install Python yourself — uv will fetch the 3.12 interpreter pinned in .python-version if it’s not already on your system.

  • The Docker container exposes IRIS on host ports 9091 (SuperServer) and 9092 (Web / Management Portal). Make sure those ports are free.

Install uv if you don't have it (via pip):

pip install uv

Related MCP server: ibmi-mcp-server

Quick start

Order matters here. The MCP server opens its IRIS connection at startup, and if IRIS isn't reachable yet every IRIS-backed tool will fail with a connection error. Stick to this order:

  1. clone the repo

  2. start the IRIS Docker container

  3. set the IRIS env vars in your MCP client config

  4. start (or restart) the MCP server from the client.

1. Clone the repo

git clone https://github.com/pietrodileo/iris-mcp-blueprint.git
cd iris-mcp-blueprint

You can perform an optional smoke-check to ensure the MCP server starts at all (this also bootstraps .venv/ from pyproject.toml + uv.lock on first run):

uv sync
uv run iris-mcp-blueprint --help

This command is only a sanity check — it prints the CLI options and exits. You will not drive the server from the terminal; real usage happens through an MCP-compatible client such as Cursor or Claude Desktop, which spawns the server itself using the JSON config in steps 3–4.

Running uv sync first is optional: it just pre-creates the venv (handy to surface install errors or to avoid MCP client startup timeouts).

2. Start the IRIS database (do this before launching the MCP server)

docker compose up -d

This starts IRIS with the SuperServer on port 9091 and the Management Portal on port 9092 (http://localhost:9092/csp/sys/UtilHome.csp). Wait until the container reports healthy (docker ps) before moving on — the MCP server cannot open a Native SDK connection until IRIS is accepting traffic on port 9091.

3. Set the IRIS connection env vars in your MCP client

Open your client's MCP config (.cursor/mcp.json, Claude Desktop's claude_desktop_config.json, etc.) and fill in the env block with the values listed in IRIS connection environment variables. Concrete JSON snippets for both clients are in Configure Cursor or Claude Desktop. Skipping or mistyping these values is the most common cause of Connection refused / Login failed errors at MCP startup.

4. Start (or restart) the MCP server from the client

Launch the server from the MCP client so it picks up the env block. In Cursor that means enabling/refreshing iris-mcp-blueprint in the MCP panel; in Claude Desktop, restart the app after editing the config. The first call goes through uv run iris-mcp-blueprint and provisions the venv on demand. If you started the server before IRIS was up, restart it now — connections are established at startup and not retried implicitly.

MCP prompts and how to try them

Prompts are short, reusable workflow instructions returned by @mcp.prompt handlers in src/iris_mcp_blueprint/prompts/prompts.py. They don't run code on their own — they just tell the assistant which tools to call and in what order (for example get_class_source, then add_production_item, then run_class_method).

Available prompts (quick reference)

Prompt name

Purpose (summary)

analyze-table

Inspect a table’s structure, sample rows, and suggest indexes.

explore-class

Read a class with get_class_source, summarize methods, properties, and storage.

import-csv-workflow

Safe CSV import: validate name, call import_csv_to_iris, verify with describe_table / fetch_data.

export-table

Export an existing table to JSON, CSV, or TXT via the export_table tool, with optional columns / where / limit filters and a row-count safety check first.

search-for-code

Search class sources with search_code, then optionally deep-dive with explore-class.

analyze-table-globals-content

Map a persistent class / table to globals and explain how data is stored.

create-rest-bp-endpoint

Wire a Business Process to HTTP: production items (EnsLib.REST.GenericService + BP), register_web_application, update_production; for MCPTest.BP.QueryService, run PopulateAndAssign before testing.

What each prompt does (more detail)

Each entry below is collapsed by default — click to see arguments and the steps the prompt walks the assistant through.

  • Arguments: table_name (required); schema_name (optional — if empty the workflow asks you to pick a schema, defaulting to SQLUser).

  • What it does: drives res_tables_all (when the schema is unknown), describe_table for columns and types, fetch_data for a small sample (first five rows), and finally writes a recommendation for indexes that would help typical access patterns.

  • Arguments: query = full class name (for example MCPTest.BP.QueryService).

  • What it does: calls get_class_source, then summarizes InstanceMethods / ClassMethods, properties, and — when present — the <Storage> block and related globals.

  • Use it when: you need a readable overview before editing or documenting code. Several other prompts chain into explore-class for deeper analysis.

  • Arguments: table_name; a csv_sample string (headers plus a few rows are enough); optional table_schema.

  • What it does: infers types from the sample, checks whether the target already exists via res_tables_all, refuses to overwrite blindly, then calls import_csv_to_iris. After load it uses describe_table and fetch_data (for example SELECT COUNT(*)) to verify shape and row counts, and may suggest create_index once you agree on names.

  • Try it with the bundled sample: paste the first few lines of example_data/patients.csv (header + a handful of rows) into csv_sample, set table_name to a fresh name such as Patients, and optionally table_schema to MCPTest (or any schema you like). The workflow will create the table and load all rows.

  • Arguments: table_name (required); format = json (default), csv, or txt; optional table_schema (the workflow asks if empty, defaulting to SQLUser).

  • What it does:

    1. Resolves the schema (via res_tables_all / get_tables if table_schema is empty).

    2. Calls describe_table to show the user the columns and types that will be exported.

    3. Runs SELECT COUNT(*) via fetch_data and warns if the table is large (>~10 000 rows).

    4. Asks the user whether to export everything (limit=0), apply a WHERE filter, restrict to a subset of columns, or keep the default limit=1000.

    5. Calls the export_table tool with the agreed scope and chosen format.

    6. Previews the first few lines/items and reports the total length, then explains how to save the output (e.g. <table_name>.<format>).

  • Tool details (export_table):

    • format — 'json' returns a list of objects (null for SQL NULL, Decimal and datetime serialized as strings); 'csv' follows RFC 4180 with a comma delimiter and CRLF line terminator; 'txt' reuses the pipe-separated table layout shared with the other SQL tools.

    • columns — optional list of column names. Each is validated as a SQL identifier ([A-Za-z_][A-Za-z0-9_]*) before being inlined.

    • where — optional SQL fragment without the leading WHERE keyword (e.g. Age > 30 AND City = 'Rome'). Caller is responsible for escaping; for untrusted input use fetch_data with parameters instead.

    • limit — defaults to 1000. Pass 0 (or a negative value) to disable the cap. Implemented as IRIS SELECT TOP N, so it streams only the requested rows.

  • Try it with the demo data: after MCPTest.Employer.PopulateAndAssign() has run (auto-seeded by iris.script on first start, or invoked via run_class_method), call the prompt with table_name: Employer, table_schema: MCPTest, format: json (or csv / txt).

  • Arguments: query = any text to find in class sources (API name, method name, ObjectScript fragment).

  • Steps: search_code → list of matching classes → you choose which hits matter → those classes are studied further (the prompt text tells the model to reuse explore-class) → short explanation of how the string appears in each chosen class.

  • Use it for: refactors, security reviews, or learning how a pattern is used in your application.

  • Arguments: table_name; optional table_schema. The class is treated as {table_schema}.{table_name} when that matches your persistent package.

  • What it does: locates every distinct global and explains its role (data vs index vs stream) and may call check_global / check_global_content or fetch_data to verify their content.

  • Use it when: you care about physical layout, not only column names.

  • Arguments: bp_class (for example MCPTest.BP.QueryService); optional bp_config_name, bs_config_name, web_app_path, production_name.

  • What it does:

    1. Verifies OnRequest / EnsLib.HTTP.GenericMessage on the BP.

    2. Ensures an active production exists.

    3. Calls add_production_item for the BP and for the REST BS (with TargetConfigNames).

    4. Calls register_web_application, then update_production, with optional list_production_items.

    5. For MCPTest.BP.QueryService, runs MCPTest.Employer:PopulateAndAssign via run_class_method to seed demo data.

    6. Applies the BS setting tweaks listed in the prompt.

    7. Documents the URL pattern http://<host>:<webport><web_app_path>/<bs_config_name> and runs an HTTP smoke test.

  • After running it: validate with the curl examples in How to test them (Cursor and similar clients).

How to test them (Cursor and similar clients)

  1. Start IRIS (docker compose up -d) and configure the MCP server using Environment variables (IRIS connection) and the JSON example under Option A — Local later in this README so the client can reach IRIS (IRIS_PORT, IRIS_NAMESPACE, credentials, etc.).

  2. In the client, open the MCP prompts UI for iris-mcp-blueprint (wording varies: “Prompts”, slash command, or the model picker’s MCP prompt list).

  3. Select a prompt by name (e.g. explore-class) and pass the parameters the prompt expects (e.g. class name MCPTest.BP.QueryService).

  4. Send the message and confirm the assistant follows the steps: it should call the listed tools and report results. If a step returns ERROR:, fix IRIS connectivity or inputs and retry.

Example inputs and full QueryService test (after IRIS is up and MCP is configured):

  • explore-class — query: MCPTest.Employer or MCPTest.BP.QueryService.

  • analyze-table — table_name: Employer, schema_name: MCPTest (or your SQL schema; leave empty to exercise schema discovery).

  • search-for-code — query: PopulateAndAssign or EnsLib.REST.GenericService.

  • analyze-table-globals-content — same table/schema as analyze-table, for example Employer / MCPTest.

  • import-csv-workflow — paste the first few lines of example_data/patients.csv into csv_sample, with table_name: Patients and an unused schema such as MCPTest. (You can also use any small fictional CSV and a new table_name that does not already exist.)

  • export-table — table_name: Employer, table_schema: MCPTest, format: json (or csv / txt). The prompt previews the data and the underlying export_table tool returns the full payload as a single string ready to copy into Employer.json / Employer.csv / Employer.txt.

  • create-rest-bp-endpoint — bp_class: MCPTest.BP.QueryService; leave other fields empty to accept the defaults the prompt proposes, or set them to match your existing production. With this repo's docker compose, the web port is mapped to 9092 on the host; a typical run of the prompt registers a CSP/REST web application under /rest/user/... and a production item QueryService-REST-BS (EnsLib.REST.GenericService) that forwards to the QueryService business process. Before calling it, ensure demo data exists by invoking the run_class_method tool with class_name: MCPTest.Employer, method_name: PopulateAndAssign, args: [] (or rely on iris.script, which populates only when the table is still empty after import). Then validate the endpoint from a shell (-i prints response headers; on macOS/Linux use curl instead of curl.exe):

    # Employees for one employer (employer-id is required for this mode)
curl.exe -sS -i "http://localhost:9092/rest/user/queryservice-rest-bs/QueryService-REST-BS" -H "service: employees" -H "employer-id: 1"

# All employers
curl.exe -sS -i "http://localhost:9092/rest/user/queryservice-rest-bs/QueryService-REST-BS" -H "service: employers"

    Expected: HTTP/1.1 200 OK and Content-Type: application/json. The service header is matched case-insensitively; employee (singular) is accepted as an alias for employees. If your web path or business service Name in production differs, replace the URL segment after /rest/user/ and the final path segment (QueryService-REST-BS) accordingly.

Configuration

This section picks up where the Quick start left off: bootstrapping a brand-new MCP server from this layout, wiring the server into Cursor and Claude Desktop, and (optionally) publishing to PyPI so others can install it with uvx.

Project layout

iris-mcp-blueprint/
├── pyproject.toml              # Package metadata + 3 runtime deps + CLI entry-point
├── uv.lock                     # Pinned transitive versions (committed)
├── docker-compose.yml          # IRIS Community container (web 9092, super 9091)
├── Dockerfile / iris.script    # Class import + optional demo data on first start
├── example_data/               # Sample CSV (e.g. patients.csv) for prompts
├── src/
│   ├── iris_mcp_blueprint/     # Python MCP server
│   │   ├── mcp_app.py          # FastMCP instance + IRIS connection lifespan
│   │   ├── entrypoint.py       # CLI entry-point (stdio / SSE transport)
│   │   ├── tools/              # @mcp.tool handlers (SQL, globals, Atelier, interop, …)
│   │   ├── prompts/            # @mcp.prompt handlers (workflows)
│   │   └── resources/          # @mcp.resource handlers (read-only data)
│   └── MCPTest/                # ObjectScript demo classes (Employer, BP/QueryService, …)
└── README.md

Only three runtime dependencies are pinned in pyproject.toml (fastmcp, intersystems-irispython, requests); the rest of the transitive graph lives in uv.lock. There's no requirements.txt.

Initialize a new MCP project

The easiest route is to clone this repo as a template and rename the package, but you can also bootstrap from scratch with uv. Either way, the pieces are always the same: a pyproject.toml script entry, a FastMCP mcp_app, and one or more @mcp.tool / @mcp.prompt / @mcp.resource handlers.

  1. Clone, then rename the package directory src/iris_mcp_blueprint/ and update the imports / entry point that reference it.

  2. In pyproject.toml, change name, description, authors, and the [project.scripts] line so the CLI command and entry-point match the new package (my-mcp = "my_mcp.entrypoint:main").

  3. Adjust IRIS-specific defaults in mcp_app.py if your server should default to a different host/port/namespace.

  4. Add or remove handlers under tools/, prompts/, resources/. Each new module must be imported from entrypoint.py (or wherever mcp_app.run() is invoked) so the decorators register before the server starts.

  5. Run uv sync once to refresh the lockfile, then uv run my-mcp --help to smoke-test the new CLI name.

uv init --package my-mcp           # creates pyproject.toml, src/my_mcp/, etc.
cd my-mcp
uv add fastmcp intersystems-irispython requests

Then, in src/my_mcp/mcp_app.py:

from fastmcp import FastMCP

mcp = FastMCP("my-mcp")

Add a tool in src/my_mcp/tools/echo.py:

from my_mcp.mcp_app import mcp

@mcp.tool()
def echo(message: str) -> str:
    """Return the message unchanged."""
    return message

Add an entry point in src/my_mcp/entrypoint.py:

from my_mcp.mcp_app import mcp

def main() -> None:
    mcp.run()

Wire it up in pyproject.toml:

[project.scripts]
my-mcp = "my_mcp.entrypoint:main"

Then uv run my-mcp launches the server over stdio.

IRIS connection environment variables

The server reads these at startup with os.getenv(). Set them wherever you launch the server from (shell, mcp.json env block, Docker environment, CI secrets store). Note that there's no automatic .env file loading.

Variable

Default

Description

IRIS_HOSTNAME

localhost

IRIS host

IRIS_PORT

9091

SuperServer TCP port (1972 is the default value for the IRIS instance, while 9091 is the value of the example Docker mapping)

IRIS_WEB_PORT

9092

Management Portal / REST APIs port (52773 is the default value for the IRIS instance, while 9092 is the value of the example Docker mapping)

IRIS_NAMESPACE

USER

IRIS namespace

IRIS_USERNAME

_SYSTEM

IRIS username

IRIS_PASSWORD

SYS

IRIS password

For SSE / HTTP transport you can also set MCP_TRANSPORT, FASTMCP_HOST, and FASTMCP_PORT (see Run the server from the terminal below).

Run the server from the terminal

The server supports two transports. Pick the one that matches how the MCP client will reach it:

Transport

When to use it

How the client connects

stdio (default)

The MCP client (Cursor, Claude Desktop, …) lives on the same machine and can spawn the server as a subprocess. This is what every example earlier in this README uses.

Client launches the command from its mcp.json and reads/writes JSON over stdin/stdout.

sse (HTTP / Server-Sent Events)

The client is on a different machine, in a sandbox, or otherwise can't spawn subprocesses. The server runs as a long-lived HTTP service and the client connects to a URL.

GET http://<host>:<port>/sse (the SSE endpoint exposed by FastMCP).

stdio (default — what Cursor / Claude Desktop normally use)

You usually do not start stdio mode by hand — your MCP client launches it for you using the JSON config in Configure Cursor or Claude Desktop. The same command works in a terminal if you want to verify it manually:

uv run iris-mcp-blueprint

The process now waits for an MCP client on stdin. Press Ctrl+C to stop. There is nothing to "open" in a browser; this transport is meant for a parent process.

sse (remote / HTTP)

Use this when the client cannot spawn the server itself — for example a remote IDE, a hosted assistant, or you want several users to share one server instance.

  1. Start the server explicitly in SSE mode and bind it to an interface and port reachable by the client. 0.0.0.0 listens on all network interfaces; 127.0.0.1 is loopback-only.

    uv run iris-mcp-blueprint --transport sse --host 0.0.0.0 --port 8000

    Equivalent using environment variables (handy in docker run, systemd units, etc.):

    MCP_TRANSPORT=sse FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=8000 uv run iris-mcp-blueprint

    Defaults if you omit them: --transport stdio, --host 127.0.0.1, --port 8000 (these are also the values returned when --help is invoked).

  2. Make sure firewalls / Docker / cloud security groups allow inbound traffic to that port from the client.

  3. Point the client at the SSE endpoint. Replace <host> with the address that is reachable from the client (localhost if it's the same machine, otherwise the public/LAN IP or DNS name); the path is always /sse:

    http://<host>:8000/sse

    In Cursor, that goes in Settings → MCP → Add server (SSE / URL). In Claude Desktop, use a JSON entry such as:

    {
  "mcpServers": {
    "iris-mcp-blueprint": {
      "url": "http://<host>:8000/sse",
      "env": {
        "IRIS_HOSTNAME": "localhost",
        "IRIS_PORT": "9091",
        "IRIS_WEB_PORT": "9092",
        "IRIS_NAMESPACE": "USER",
        "IRIS_USERNAME": "_SYSTEM",
        "IRIS_PASSWORD": "SYS"
      }
    }
  }
}

  4. Quick smoke-test from any host that can reach the URL — the SSE endpoint should keep the connection open and stream events (you'll see event: / data: lines):

    curl -N http://<host>:8000/sse

Security note: SSE mode does not add authentication on top — anyone who can reach the URL can call the tools (and therefore your IRIS instance). Bind to 127.0.0.1, put a reverse proxy in front, or run it inside a private network.

Configure Cursor or Claude Desktop

There are two distribution modes for any MCP client config: local (uv run against a clone you maintain locally) and remote (uvx pulling the package from GitHub or PyPI on demand). Pick one per server — they're not meant to be combined.

Local (uv run)

Remote (uvx)

Requires cloning the repo

Yes

No

Reads pyproject.toml / uv.lock from

Local disk

GitHub / PyPI

Builds a wheel

No (editable source)

Yes (temporary, invisible)

Changes to .py files

Reflected immediately

Require a new commit + push (or republish)

Best for

Development

Sharing / distribution

1. Local: uv run against a cloned MCP

Clone this GitHub repository on a local folder and run the Docker container.

Cursor — create or edit .cursor/mcp.json in the repo root. Cursor uses the workspace folder as the MCP server's working directory, so a plain uv command works without any extra path:

{
  "mcpServers": {
    "iris-mcp-blueprint": {
      "command": "uv",
      "args": ["run", "iris-mcp-blueprint"],
      "env": {
        "IRIS_HOSTNAME": "localhost",
        "IRIS_PORT": "9091",
        "IRIS_WEB_PORT": "9092",
        "IRIS_NAMESPACE": "USER",
        "IRIS_USERNAME": "_SYSTEM",
        "IRIS_PASSWORD": "SYS"
      }
    }
  }
}

Other top-level keys you may already have in the .json file can stay alongside mcpServers.

Claude Desktop — Claude Desktop does not inherit a workspace folder, and on Windows the uv executable is often outside of Claude's PATH. To make a local launch reliable you usually have to:

  1. Point command at the absolute path to uv.exe (or to the uv binary on macOS / Linux).

  2. Pass --directory <repo-root> to uv so it finds pyproject.toml.

Config file locations:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Replace the two absolute paths with yours.

{
  "mcpServers": {
    "iris-mcp-blueprint": {
      "command": "C:\\Users\\<you>\\.local\\bin\\uv.exe",
      "args": [
        "--directory",
        "C:\\path\\to\\iris-mcp-blueprint",
        "run",
        "iris-mcp-blueprint"
      ],
      "env": {
        "IRIS_HOSTNAME": "localhost",
        "IRIS_PORT": "9091",
        "IRIS_WEB_PORT": "9092",
        "IRIS_NAMESPACE": "USER",
        "IRIS_USERNAME": "_SYSTEM",
        "IRIS_PASSWORD": "SYS"
      }
    }
  }
}

Find your own uv.exe location with where uv in Windows Terminal (typically C:\Users\<you>\.local\bin\uv.exe after pip install uv).

On macOS / Linux a similar shape works. Just adjust the uv path and use a forward-slash repo path.

After editing the JSON, fully quit Claude Desktop from the system tray (closing the window is not enough) and relaunch. Cursor only needs the MCP server reload icon.

2. Remote: uvx from GitHub or PyPI

uvx downloads the package, builds it in a temporary isolated environment, and runs it — no clone, no uv sync, no manual venv. The user only needs uv installed.

Adjust IRIS_* for your environment.

Cursor — .cursor/mcp.json (uses just uvx; Cursor inherits PATH so this works on Windows, macOS, and Linux):

{
  "mcpServers": {
    "iris-mcp-blueprint": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/pietrodileo/iris-mcp-blueprint.git",
        "iris-mcp-blueprint"
      ],
      "env": {
        "IRIS_HOSTNAME": "localhost",
        "IRIS_PORT": "9091",
        "IRIS_WEB_PORT": "9092",
        "IRIS_NAMESPACE": "USER",
        "IRIS_USERNAME": "_SYSTEM",
        "IRIS_PASSWORD": "SYS"
      }
    }
  }
}

Claude Desktop on Windows — claude_desktop_config.json (use the absolute path to uvx.exe):

{
    "mcpServers": {
        "iris-mcp-blueprint": {
            "command": "C:\\Users\\p.dileo\\.local\\bin\\uvx.exe",
            "args": [
                "--from", "git+https://github.com/pietrodileo/iris-mcp-blueprint.git",
                "iris-mcp-blueprint"
            ],
            "env": {
                "IRIS_HOSTNAME": "localhost",
                "IRIS_PORT": "9091",
                "IRIS_WEB_PORT": "9092",
                "IRIS_NAMESPACE": "USER",
                "IRIS_USERNAME": "_SYSTEM",
                "IRIS_PASSWORD": "SYS"
            }
        }
    }
}

You can wire it into any client mcp.json using uvx and calling directly package name iris-mcp-blueprint:

{
  "mcpServers": {
    "iris-mcp-blueprint": {
      "command": "uvx",
      "args": ["iris-mcp-blueprint"],
      "env": { "IRIS_HOSTNAME": "...", "IRIS_PORT": "1972" }
    }
  }
}

Publish to PyPI

Once the project is ready to share, build a wheel and upload it to PyPI so anyone with uv installed can run it via uvx iris-mcp-blueprint without cloning the repo first.

  1. Bump the version. PyPI rejects re-uploads of an existing version, so every release needs a new number. Use uv version to update pyproject.toml (and uv.lock) in one step:

    uv version --bump patch    # 0.1.0 -> 0.1.1
uv version --bump minor    # 0.1.0 -> 0.2.0
uv version --bump major    # 0.1.0 -> 1.0.0
uv version 1.2.3           # set an explicit version
uv version                 # just print the current version

  2. Build distributable artifacts:

    uv build      # writes sdist + wheel into dist/

  3. Get a PyPI token. Log in to PyPI and create an API token (project-scoped is recommended once the project exists; otherwise use an account-wide token for the first upload). The token always starts with pypi-.

  4. Publish with the token. Export the token as UV_PUBLISH_TOKEN so it does not end up in your shell history; uv publish reads it automatically:

    # Linux / macOS / Git Bash
export UV_PUBLISH_TOKEN=pypi-<your-token>
uv publish

# PowerShell
$env:UV_PUBLISH_TOKEN = "pypi-<your-token>"
uv publish

  5. Verify the public install (uses the freshly uploaded version, no git needed):

    uvx iris-mcp-blueprint --help

After a successful upload, switch any client mcp.json from the GitHub form to the simpler PyPI form shown above.

Available Tools

26 tools
add_production_itemB

Add a Business Host (Service / Process / Operation) to a production on the current namespace.

ParametersJSON Schema
NameRequiredDescriptionDefault
class_nameYesFull class name of the host (e.g. 'EnsLib.REST.GenericService', 'MCPTest.BP.QueryService').
config_nameYesConfig name of the new item inside the production.
production_nameNoProduction class name. If empty, the active production is used.
commentNoOptional comment shown in the production page.
pool_sizeNoPool size (jobs). Use 0 for on-demand BPL processes.
enabledNoWhether the item is enabled at startup.
settingsNoOptional dict of {SettingName: value} pairs applied as Host settings. Typical example for a BS routing to a BP: {"TargetConfigNames": "MyBP"}

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/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 fully disclose behavior. It only states the basic action, failing to describe side effects (e.g., compilation, need for restart), error conditions, or permission requirements. This is insufficient for a tool that modifies a running production.

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 directly states the purpose, making it compact and easy to parse. It could benefit from slightly more context without becoming verbose, but it is 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 the tool's complexity (7 parameters, modifies a production, 26 sibling tools), the description is too sparse. It does not mention prerequisites (e.g., production must exist), the output/return value (output schema exists but not described), or how this interacts with the active production.

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 100% schema description coverage, the schema already documents all parameters thoroughly. The description adds no additional meaning beyond what the schema provides, so a 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 action (Add), the resource (Business Host to a production), and the context (on the current namespace). It uses specific terms like Service/Process/Operation which are meaningful in the domain, and distinguishes from sibling tools like remove_production_item or update_production_item_settings.

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 the tool is used to add a host to a production, but does not specify when to use this tool versus alternatives like create_empty_production (if production doesn't exist) or update_production_item_settings (to modify an existing item). No when-not 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.

check_globalB

Check if a global exists (e.g., 'MCPData'). Args: ctx: The context of the tool call. global_name: The name of the global to check.

ParametersJSON Schema
NameRequiredDescriptionDefault
global_nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided. The description only states 'Check if a global exists' without disclosing return behavior (e.g., true/false, error handling) or other operational details. The agent lacks information on what happens when the global does or does not exist.

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 short and to the point with two sentences. It is not verbose, but could be better structured by separating the purpose from parameter details.

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 simple with one parameter and an output schema exists (not shown). However, lacking annotations and behavioral details, the description is minimally adequate for a basic existence check but 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 description coverage is 0%. The description adds only the example 'MCPData' and repeats the parameter name from the schema. It does not clarify expected format, constraints, or how the parameter is used beyond the minimal schema information.

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 checks if a global exists, using a specific verb and resource, and includes an example ('MCPData'). It distinguishes from sibling 'check_global_content' which likely checks content, not existence.

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 (check existence before using a global) but provides no explicit guidance on 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.

check_global_contentC

Read a global node (same subscript rules as save_global). Args: ctx: The context of the tool call. global_name: The name of the global to read. subscripts: The subscripts of the global to read.

ParametersJSON Schema
NameRequiredDescriptionDefault
global_nameYes
subscriptsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.8/5.0
Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It states 'Read a global node', implying idempotency, but does not mention error handling, default behavior for missing globals, or 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.

Conciseness3/5

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

The description is relatively short but includes redundant line-by-line parameter descriptions that add little beyond the schema. It is adequately structured but could be more concise.

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 presence of an output schema, the return value is covered, but the description omits important context such as error cases, null return expectations, and the nature of the global storage. Minimal 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 description coverage is 0%, so the description adds value by naming and briefly explaining the two parameters. The reference to 'same subscript rules as save_global' provides context, but parameter formats and constraints are not detailed.

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 'Read a global node', indicating a read operation. However, it does not differentiate from the sibling tool 'check_global', which may have a similar purpose.

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 vs alternatives. The description mentions 'same subscript rules as save_global' but does not give usage context or exclusions.

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

create_empty_productionA

Create and compile a new empty Ens.Production subclass in the current namespace.

Uses the Atelier REST API (PutDoc + action/compile) — same web host/credentials as other Atelier tools (IRIS_WEB_PORT, IRIS_ATELIER_API_VERSION).

ParametersJSON Schema
NameRequiredDescriptionDefault
production_class_nameYesFull class name (e.g. `MyPkg.MyProduction`). Must contain at least one package segment. The `ProductionDefinition` XData will use this exact name as the production name.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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 cover behavioral traits. It mentions creation and compilation via Atelier API and references credentials, which adds some context. However, it does not disclose potential side effects (e.g., overwriting existing classes), error handling, or return behavior beyond what an output schema might cover.

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, each earning its place: first sentence states primary action, second provides essential implementation detail. There is no waste, and the most critical information (creating and compiling an empty production) is front-loaded.

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?

With an output schema present, the description does not need to explain return values. However, it lacks discussion of error conditions, compilation success criteria, or permissions. Given the tool's complexity (creation + compilation), moderate additional context would improve completeness, but current level is satisfactory.

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 100%, and the parameter description in the schema is already detailed (full class name, package requirement, XData naming). The description in the tool text adds no new parameter information beyond what the schema provides, 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 the verb 'Create and compile' and the resource 'Ens.Production subclass'. It distinguishes itself from sibling tools like 'add_production_item' and 'update_production' by specifying it creates an empty production, leaving 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 Guidelines3/5

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

The description implies usage for creating new empty productions but does not explicitly state when to use this tool over alternatives, nor does it mention prerequisites or constraints beyond the parameter. 'Uses the Atelier REST API' provides context but not clear when/when-not guidance.

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

create_indexC

Creates a standard index to speed up queries. Args: ctx: The context of the tool call. table_name: The name of the table to create the index on. column_name: The name of the column to create the index on. index_name: The name of the index to create. table_schema: The schema of the table to create the index on.

ParametersJSON Schema
NameRequiredDescriptionDefault
table_nameYes
column_nameYes
index_nameNo
table_schemaNoSQLUser

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.8/5.0
Behavior2/5

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

No annotations are present, so the description must carry the burden. It does not disclose behavioral traits such as error handling on duplicate indexes, required permissions, or performance implications. It only implies a write operation.

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 short but includes redundant parameter repetition that could be handled by the schema. The inclusion of 'ctx' adds noise. It is front-loaded with the purpose, but the structure could be tighter.

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's complexity (4 parameters, no annotations), the description is insufficient. It omits crucial context such as return value behavior, error scenarios, and whether the operation is idempotent. The presence of an output schema reduces the burden for return values, but behavioral gaps remain.

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 lists each parameter with a brief explanation (e.g., 'The name of the table to create the index on'), which adds value beyond the schema's type-only definitions. However, it lacks details on defaults, constraints, or formats.

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 ('Creates a standard index') and the purpose ('to speed up queries'). It is specific enough to distinguish from sibling tools, which are mostly about production items, globals, and data manipulation.

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 usage guidance is provided. The description does not indicate when to use this tool vs alternatives, nor does it mention prerequisites or scenarios where other tools are preferable.

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

describe_tableC

Show columns and types for a table. Args: ctx: The context of the tool call. table_name: The name of the table to describe. table_schema: The schema of the table to describe.

ParametersJSON Schema
NameRequiredDescriptionDefault
table_nameYes
table_schemaNoSQLUser

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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

Without annotations, the description carries full burden for behavioral disclosure. It does not mention whether the operation is read-only (though implied), nor does it discuss error handling, permissions, or performance implications. The description only states what the tool does, not its side effects or constraints.

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 and front-loaded with the primary purpose. The 'Args' section is slightly redundant but adds clarity for parameter semantics. Every sentence contributes meaning without excess.

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 presence of an output schema, the description does not need to detail return values. However, it lacks contextual details such as behavior for non-existent tables, schema resolution, or interaction with permissions. For a simple read tool, this is adequate but not 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 parameter explanations ('The name of the table...', 'The schema of the table...'), which add meaning beyond the bare schema (which has 0% coverage). However, it does not explain the default value of 'table_schema' or any constraints on the parameters, leaving some gaps.

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 'Show columns and types for a table', which is a clear verb-resource combination. It effectively distinguishes from siblings like 'get_tables' (which lists tables) and 'fetch_data' (which retrieves rows). However, it could be slightly more explicit about the output being metadata.

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, such as 'fetch_data' for actual data retrieval or 'get_tables' for table listing. There is no mention of prerequisites (e.g., table existence) or exclusion scenarios.

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

export_tableA

Export rows from an existing IRIS table as JSON, CSV, or TXT (pipe-separated).

The result is returned as a single string the caller can preview, copy to a file, or stream to a downstream client. For large tables narrow the result with columns, where, and/or limit to keep responses manageable.

ParametersJSON Schema
NameRequiredDescriptionDefault
table_nameYesBare table name (letters, digits, underscore; no schema, no dot).
table_schemaNoSchema of the table (default 'SQLUser').SQLUser
formatNoOutput format — 'json' (list of objects), 'csv' (RFC 4180, comma delimiter, CRLF line terminator), or 'txt' (pipe-separated columns + ruler, same look as other tools' output). Case-insensitive.json
columnsNoOptional list of column names to export. None or empty = all columns.
whereNoOptional SQL fragment placed after WHERE (do **not** include the 'WHERE' keyword). Example: "Age > 30 AND City = 'Rome'". Caller is responsible for escaping; consider parameterized fetch_data for untrusted input.
limitNoMaximum number of rows to return. Pass 0 or a negative value to disable the cap (use only for known-small tables).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/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 full burden. It describes the output as a single string for preview or streaming, and recommends narrowing for large tables. It does not explicitly state that the operation is read-only, but that is implied by 'export'. Minor gap: no mention of idempotency or 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 two short paragraphs, front-loaded with the main action, and every sentence adds value. No redundancy or 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 has an output schema (not shown), and the description covers purpose, formats, and output type. It could mention how empty results or errors are handled, but overall it is complete for a simple export 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?

Schema description coverage is 100%, so baseline is 3. The description reinforces the use of columns, where, and limit for narrowing, but does not add significant new semantics 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 (export), the resource (IRIS table), and the output formats (JSON, CSV, TXT). It distinguishes from siblings like fetch_data by specifying the format options and return 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 advises narrowing results for large tables using columns, where, and limit, and warns against using limit 0 for unknown-large tables. However, it does not explicitly compare to sibling tools like fetch_data to guide selection.

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

fetch_dataB

Execute SQL and return results as a table. For DDL/DML with no result set, returns a short status line. Args: ctx: The context of the tool call. sql: The SQL query to execute. parameters: The parameters to pass to the SQL query.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYes
parametersNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior3/5

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

Mentions DDL/DML behavior and status line, but does not explicitly disclose side effects or permissions needed, relying on the agent's general knowledge.

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, front-loaded purpose, but includes 'ctx' not in schema which is a minor distraction.

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 basic I/O and DDL/DML case, but lacks guidance on when to use vs siblings and no error handling info.

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?

Adds basic meaning to sql and parameters beyond schema types, but lacks detail on parameter format or constraints; coverage is 0% so description compensates partially.

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 executes SQL and returns a table, distinguishing it from siblings like insert_data or create_index which are more 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 guidance on when to use this tool versus alternatives like insert_data or create_index; the description simply defines behavior without context.

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

get_active_productionA

Return the name of the currently active Interoperability production on the current namespace.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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 carries full burden. It correctly indicates a read-only retrieval with no side effects. The behavior is fully disclosed for a simple getter.

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?

A single sentence with no wasted words. The description is optimally concise.

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 the presence of an output schema, the description is complete. It covers the core function without missing details.

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?

No parameters exist, so the description doesn't need to add param info. It is concise and sufficient.

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 the name of the currently active Interoperability production on the current namespace. It uses a specific verb ('return') and resource ('active production'), and it distinguishes from sibling tools like start_production or stop_production.

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 checking the active production but does not explicitly state when to use this tool versus alternatives like list_production_items or get_production_item_settings. No when-not or context on prerequisites is provided.

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

get_class_sourceA

Read .cls source code using Atelier REST API.

ParametersJSON Schema
NameRequiredDescriptionDefault
class_nameYesThe name of the class to get the source code for.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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 responsibility. It correctly indicates a safe read operation, but does not disclose potential requirements (e.g., Atelier REST API availability) or any side effects. The output schema presumably covers return format, so 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.

Conciseness4/5

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

The description is a single, concise sentence that gets directly to the point. It is front-loaded and wastes no words. However, it could include slightly more detail without becoming verbose.

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 parameter, no annotations) and the presence of an output schema, the description is nearly complete. It could mention the need for a running Atelier REST API, but overall it suffices for understanding the tool's function.

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 100% schema description coverage for the single parameter, the description adds no additional meaning beyond what the schema already provides. 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 action (Read), resource (.cls source code), and method (Atelier REST API). It distinguishes from siblings like search_code and run_class_method, making the tool's purpose unmistakable.

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 no guidance on when to use this tool versus alternatives, nor any prerequisites or restrictions. It is adequate but lacks explicit usage context.

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

get_production_item_settingsA

List the configured setting overrides on a Business Host (Service / Process / Operation) inside a production.

Only settings explicitly stored on the Ens.Config.Item are returned — settings that still use the class-level defaults are NOT listed (they are not present in item.Settings). The output combines both Host and Adapter targets and is meant as input to update_production_item_settings.

ParametersJSON Schema
NameRequiredDescriptionDefault
config_nameYesConfig name of the Business Host.
production_nameNoProduction class name. If empty, the active production is used.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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 carries full transparency burden. It explains what is returned (only explicit overrides), what is excluded (class-level defaults), and combines Host and Adapter targets. It does not cover permissions or side effects, but for a read-only tool it 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?

Three concise sentences front-load the main purpose, include important filtering behavior, and reference a sibling tool. Every sentence adds value without waste.

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, the presence of an output schema, and full parameter documentation, the description covers the essential context: what is listed, what is not, and how the output is used. No gaps remain.

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%, so baseline is 3. The description does not add parameter-specific meaning beyond the schema descriptions; it only restates the context. No additional value is provided.

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 lists configured setting overrides on a Business Host, specifying the resource (Business Host) and action (list overrides). It distinguishes from siblings by focusing on settings overrides, not general item listing.

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 only explicitly stored settings are returned, implying its use for viewing overridden settings. It also states the output is input to update_production_item_settings, providing context. However, it does not explicitly exclude 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.

get_tablesC

List all tables in a specific schema. Args: ctx: The context of the tool call. table_schema: The schema of the tables to list.

ParametersJSON Schema
NameRequiredDescriptionDefault
table_schemaNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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 does not disclose any behavioral traits such as read-only nature, side effects, or required permissions. For a list operation, it's low risk, but the lack of disclosure is 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.

Conciseness3/5

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

The description is short but includes unnecessary 'Args:' section that repeats parameter names. It could be more concise, but overall it's not overly 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?

While an output schema exists (covering return values), the description does not explain the default behavior when no schema is provided, nor does it clarify if 'all tables' spans all schemas or just public ones. This leaves ambiguity for the agent.

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%. The description only restates the parameter name ('table_schema: The schema of the tables to list') without adding any additional meaning, constraints, or examples.

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 'List all tables in a specific schema,' which is a specific verb and resource. It differentiates from sibling tools like 'describe_table' which likely describes a single table.

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. No mention of prerequisites or context where this tool is appropriate.

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

import_csv_to_irisB

Creates a table and imports data from a CSV string. The first row of the CSV must be the header (column names). All columns will be created as VARCHAR(255) for this blueprint. Args: ctx: The context of the tool call. table_name: The name of the table to import the data into. csv_content: The content of the CSV file to import. table_schema: The schema of the table to import the data into.

ParametersJSON Schema
NameRequiredDescriptionDefault
table_nameYes
csv_contentYes
table_schemaNoSQLUser

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/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 discloses the column type limitation and header requirement, but does not mention error handling, behavior when table already exists, or concurrency issues.

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 purpose, and avoids unnecessary words. The Args section is slightly redundant but acceptable.

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 an output schema exists (reducing need for return value description), the description lacks details on failure modes, table existence handling, and encoding. It provides basic but not comprehensive 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%. The description merely repeats parameter names with vague definitions (e.g., 'The name of the table'). No format details for csv_content or clarification of table_schema default are provided.

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 table and imports data from a CSV string. It distinguishes itself from siblings by specifying CSV import and column type limitation (VARCHAR(255)).

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 like insert_data or export_table. No explicit context or exclusion criteria are given.

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

insert_dataC

Insert a single row into a table. Args: ctx: The context of the tool call. table_name: The name of the table to insert the data into. values: The values to insert into the table. table_schema: The schema of the table to insert the data into.

ParametersJSON Schema
NameRequiredDescriptionDefault
table_nameYes
valuesYes
table_schemaNoSQLUser

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.8/5.0
Behavior2/5

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

No annotations exist, and the description does not disclose behavioral traits like error handling, side effects, or concurrency behavior. It only states the basic action without any depth about what happens during insertion (e.g., duplicate key 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 relatively short and front-loaded with the main action. The 'Args' section adds structure, though it could be slightly more concise by removing the redundant 'Args:' line. Overall, it efficiently conveys the core purpose without excessive text.

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 existence of an output schema (though not detailed), the description lacks information about return values or expected behavior. The tool has 3 parameters (2 required) and is straightforward, but additional context about data validation, success/failure indicators, or typical use cases would improve completeness. It is minimally adequate.

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?

While the description lists parameters in an 'Args' block and provides brief comments (e.g., 'The values to insert into the table'), it lacks important semantic details. For instance, the 'values' parameter format (likely a dictionary) is not specified, and 'table_schema' defaults to 'SQLUser' with no explanation. With 0% schema description coverage, the description should compensate but fails to provide sufficient meaning beyond the 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 'Insert a single row into a table' which specifies the verb and resource. However, it does not differentiate from sibling tools like 'fetch_data' or 'save_global', which could cause confusion. The purpose is clear but lacks sibling distinction.

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, such as when to use 'import_csv_to_iris' for bulk inserts or how to handle schema validation. There are no prerequisites or contextual hints.

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

list_global_subscriptsA

List subscript keys under a global path using the IRIS node iterator (ZORDER-style). Args: ctx: The context of the tool call. global_name: top global without ^ (e.g. BTHo). subscripts: path into the global, e.g. ["DufT", 3] for ^BTHo("DufT",3,... recursive: if True, each line is a full path from the start node; max_depth is how many subscript levels to descend below the starting path (1 = only immediate children). max_depth: how many subscript levels to descend below the starting path (1 = only immediate children). max_nodes: maximum number of nodes to return (default: 2000). include_values: if True, include the values of the nodes.

ParametersJSON Schema
NameRequiredDescriptionDefault
global_nameYes
subscriptsNo
recursiveNo
max_depthNo
max_nodesNo
include_valuesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

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

Describes the ZORDER-style iteration, recursion behavior, max_nodes limit, and include_values option. No annotations provided, so description carries burden; it sufficiently explains the read-only nature and major behaviors.

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?

Well-structured with bullet points for parameters and clear hierarchical purpose statement. Slightly verbose but every sentence adds value; could be tightened slightly.

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 parameters well and output schema exists, so return format is not needed. Lacks mention of error conditions or performance considerations, but overall adequate for a listing 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?

Schema description coverage is 0%, but the description thoroughly explains all 6 parameters, adding meaning (e.g., 'global without ^', 'path into the global', default values, behavior of recursive and max_depth). Greatly 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?

Clearly states the tool lists subscript keys under a global path using IRIS node iterator. Differentiates from siblings (e.g., check_global, save_global) by focusing on subscripts listing.

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 versus alternatives. Does not mention when not to use or provide context for selecting this over other global-related tools.

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

list_production_itemsB

List the items currently configured in a production on the current namespace.

ParametersJSON Schema
NameRequiredDescriptionDefault
production_nameNoProduction class name. If empty, the active production is used.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/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 only says 'list', implying read-only, but fails to state safety, permissions, or behavior for non-existent productions. No mention of output format despite having an output 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?

Single sentence, ten words, directly front-loads the action and resource. No extraneous 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?

Basic description covers purpose but lacks details on output content or edge cases. Given existence of an output schema and related sibling tools, the description is minimally adequate.

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 already provides parameter description (production class name). The description adds context of 'current namespace' which provides additional scope clarity beyond the 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 the verb 'list' and the resource 'items configured in a production' within a scope ('current namespace'). It distinguishes from siblings like add/remove/update but does not specify what constitutes an 'item'.

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 when-to-use guidance or alternatives. It implies listing items but does not advise when not to use, such as for detailed settings which might be better covered by get_production_item_settings.

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

register_web_applicationA

Create or update a CSP web application that exposes an HTTP-based Business Service (typically EnsLib.REST.GenericService) to the outside world.

Delegates to the ObjectScript helper because 'Security.Applications' requires switching to the %SYS namespace, which is cleaner to do in ObjectScript than over the Native SDK.

Authentication is set to Unauthenticated for development convenience. Tighten this before going to production.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesURL path of the web app (must start with '/'), e.g. '/rest/user/queryservice-rest-bs' or '/csp/myapp/api' depending on Security.Applications registration.
dispatch_classNoClass that handles incoming requests. Defaults to 'EnsLib.REST.GenericService' which forwards everything to the Business Service whose config name appears next in the URL.EnsLib.REST.GenericService
descriptionNoFree-text description shown in the Management Portal.REST endpoint exposed via the MCP blueprint
namespaceNoTarget namespace. If empty, uses the namespace of the current MCP connection.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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 important behaviors: delegation to ObjectScript helper for namespace switching, default authentication setting (Unauthenticated) with a production security warning, and default dispatch class. However, it does not specify if the operation is idempotent or any other 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 (three sentences) and well-structured, front-loading the purpose, then providing technical detail. 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 existence of an output schema (context signal) and high schema coverage, the description is fairly complete. It covers purpose, technical implementation details, and security caveats. One could argue for more detail on error conditions or rollback, but it's 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 100%, so the schema already describes all parameters. The description adds no additional meaning beyond what is in the schema (e.g., no extra context for path, namespace, etc.). Baseline 3 applies.

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 ('Create or update') and the resource ('CSP web application'), with specific detail about exposing an HTTP-based Business Service. It distinguishes from siblings like 'remove_web_application'.

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 use for registering web applications for Business Services but does not explicitly state when to use or avoid this tool over alternatives. No guidance on when not to use it (e.g., for non-Business Service apps).

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

remove_production_itemC

Remove a Business Host from a production.

ParametersJSON Schema
NameRequiredDescriptionDefault
config_nameYesConfig name of the item to remove.
production_nameNoProduction class name. If empty, the active production is used.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It only states the action 'remove' without indicating whether it is destructive, reversible, or requires permissions. The agent cannot infer consequences.

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, clear sentence with no wasted words. It front-loads the action and resource.

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 having an output schema, the description does not cover what happens upon removal (e.g., success indication, errors). For a mutation tool with no annotations, this is inadequate.

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 100%, so the baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions, but it does not detract either.

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 removes a Business Host from a production. It uses a specific verb and resource, distinguishing it from siblings like add_production_item. However, 'Business Host' is jargon that could be clarified.

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 vs alternatives. It does not mention prerequisites, conditions for removal, or relation to other tools like add_production_item or update_production.

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

remove_web_applicationA

Delete a CSP web application by URL path (delegates to ObjectScript).

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesURL path of the web app (must start with '/'), e.g. '/rest/user/queryservice-rest-bs'.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior2/5

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

No annotations provided, so description carries full burden. Only mentions 'delegates to ObjectScript' but lacks details on side effects, permissions, reversibility, or return behavior. A deletion tool should disclose more 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?

One sentence of 12 words, front-loaded with action and resource. 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?

For a simple one-parameter tool with output schema, the description covers purpose and parameter, but lacks usage guidelines and behavioral transparency. It is adequate but not 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 description coverage is 100%, and the schema already explains the 'path' parameter well. The description adds little beyond 'by URL path', which matches schema. Baseline 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?

Description clearly states the action 'Delete', the resource 'CSP web application', and the method 'by URL path'. It distinguishes from siblings like 'register_web_application' and 'remove_production_item'.

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 verb and resource, but no explicit guidance is given on when to use this tool versus alternatives, or any prerequisites or conditions.

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

run_class_methodC

Run an ObjectScript ClassMethod. Args: ctx: The context of the tool call. class_name: The name of the class to run the method on. method_name: The name of the method to run. args: The arguments to pass to the method.

ParametersJSON Schema
NameRequiredDescriptionDefault
class_nameYes
method_nameYes
argsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/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 potential side effects, authentication requirements, or whether the method may modify data. A generic method runner could be destructive, but this is 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?

The description is short and to the point, using a structured 'Args:' list. Every sentence adds value, though it could be more detailed without being 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?

With an output schema present but not described, and 0% schema description coverage, the description lacks completeness. It does not explain return values or behavior for non-existent methods, leaving ambiguity.

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 includes a docstring-style list explaining each parameter (class_name, method_name, args), adding meaning beyond the bare schema. However, schema coverage is 0%, so the description compensates minimally but adequately.

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 'Run an ObjectScript ClassMethod,' which clearly specifies the action and resource. It distinguishes from siblings by specifying ObjectScript, though it could be more explicit about what a ClassMethod is.

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 alternative tools like 'get_class_source' or 'describe_table'. There is no mention of prerequisites, limitations, 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.

save_globalB

Save a value to a global node. Use subscripts for ^g(1,"a") style paths (e.g. [1, "Prova"]). Args: ctx: The context of the tool call. global_name: The name of the global to save the value to. value: The value to save to the global. subscripts: The subscripts of the global to save the value to.

ParametersJSON Schema
NameRequiredDescriptionDefault
global_nameYes
valueYes
subscriptsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations provided, the description should disclose behavioral traits. It mentions subscripts for paths but fails to indicate whether the operation overwrites, is destructive, requires permissions, 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.

Conciseness4/5

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

The description is brief and gets to the point, but could be more structured (e.g., separate usage from parameter list). Still, it's not verbose.

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 (3 parameters, output schema exists), the description is adequate but lacks details about return values and behavior like idempotency or creation 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?

The input schema has 0% description coverage, so the description must compensate. It lists parameters but adds minimal meaning beyond names, except for subscripts hinting at path syntax. Value and global_name are merely restated.

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 ('Save a value to a global node') and specifies the resource. It distinguishes from sibling tools like check_global or list_global_subscripts by implying a write operation.

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 saving values to a global node but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusion conditions.

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

search_codeA

Search for a string across IRIS source documents (Atelier action/search).

Calls GET /api/atelier/<ver>/<ns>/action/search (v2+). Both query and documents are required by the server; missing documents returns HTTP 400.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesText (or regex) to search for.
documentsNoComma-separated file mask (default `*.cls,*.mac,*.int,*.inc`).*.cls,*.mac,*.int,*.inc
regexNo1 = treat `query` as a regex, 0 = plain-text (default).
case_sensitiveNo1 = case-sensitive, 0 = case-insensitive (default). Only honoured when `regex=0`.
include_systemNo1 = include system docs (e.g. `%Api.*`), 0 = skip (default).
include_generatedNo1 = include generated docs, 0 = skip (default).
max_resultsNoMax number of hits to return (default 50).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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 behavioral disclosure burden. It reveals a critical server-side requirement (both query and documents are mandatory) and the resulting error (HTTP 400 if documents is missing). This goes beyond the input schema, which marks only query as required. It does not discuss other behaviors like pagination or performance, but the core safety and contractual obligation are well communicated.

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—only two sentences totaling about 70 words. The first sentence immediately conveys the tool's purpose, and the second delivers critical contractual information. No extraneous detail is included.

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 search tool with 7 parameters and an output schema, the description adequately covers the primary use. The mention of the server-side requirement adds completeness. However, it does not explicitly state that the operation is read-only (though implied by 'search') or describe the return structure, but the presence of an output schema likely covers that. Overall, it is sufficiently complete for an agent to invoke the tool 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?

The input schema already provides 100% coverage with descriptions for all 7 parameters. The description adds value by clarifying the implicit server requirement for the 'documents' parameter, which is not reflected as required in the schema. This extra context helps the agent understand a potential failure point.

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 'Search' and the resource 'IRIS source documents', making the purpose unambiguous. It also distinguishes itself from siblings like 'get_class_source' which retrieves a specific class rather than searching across documents.

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 does not explicitly specify when to use this tool over alternatives, nor does it state when not to use it. However, it does provide a crucial usage constraint: both 'query' and 'documents' are required server-side, which helps the agent avoid HTTP 400 errors. No comparison with sibling tools is provided.

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

start_productionA

Start an Interoperability production by class name (must already exist and be compiled).

Calls ##class(Ens.Director).StartProduction(productionName) (single-argument form compatible with the IRIS Native SDK and servers where the two-argument sync overload is not exposed to Python). It does not create the production class; use create_empty_production or deploy a class from source, then call this tool.

ParametersJSON Schema
NameRequiredDescriptionDefault
production_class_nameYesFull production class name (e.g. `MCPTest.EmptyProduction`).
synchronousNoReserved for future use; start mode follows the server's single-arg API.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

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

No annotations provided, so description must cover behavioral traits. It mentions the specific API call and compatibility notes, but does not disclose side effects, error conditions, or authentication 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?

Description is three sentences, front-loaded with main action, no extraneous words, 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 no annotations and presence of output schema, description covers prerequisites, API call, and distinguishes from creation tools. Could mention return values or error handling, 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 has 100% coverage; description adds minimal extra info about synchronous parameter being reserved and the single-argument API, but does not elaborate on parameter semantics 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?

Description clearly states verb 'Start' and resource 'Interoperability production by class name', and differentiates from tools that create productions (e.g., create_empty_production).

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 prerequisite (must exist and be compiled) and what it does NOT do (create the class), directing users to alternatives like create_empty_production or deploy from source.

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

stop_productionA

Stop the currently running Interoperability production in this namespace.

Calls ##class(Ens.Director).StopProduction().

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior2/5

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

No annotations exist, so the description must fully disclose behavior. It only states it stops the production and calls a method. It omits details such as whether it is synchronous, side effects on ongoing processes, or required permissions. The description is insufficient for safe use.

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. The purpose is front-loaded in the first sentence, and the second sentence provides a technical reference. Every word earns its place.

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 (no parameters, output schema exists), the description is minimally adequate. However, it lacks context about prerequisites or potential impacts. An output schema is present (not shown), but the description doesn't clarify the return value or confirm the action. For a production-critical operation, more context is advisable.

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 zero parameters, the baseline is 4. The description does not need to explain parameters, but it does confirm the tool requires no input, which is appropriate. The purpose is clear even without parameter details.

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 and resource: 'Stop the currently running Interoperability production'. It clearly distinguishes from sibling tools like start_production and update_production. The technical detail about calling Ens.Director.StopProduction() 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 Guidelines2/5

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

The description does not provide guidance on when to use this tool, e.g., prerequisites like ensuring a production is running, or alternatives. It lacks context about when not to use it, which is especially important given sibling tools that might be confused.

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

update_productionA

Apply pending configuration changes to the running production (equivalent to clicking 'Update' in the Management Portal).

Calls ##class(Ens.Director).UpdateProduction(). Only the active production is updated; production_name is reserved for future use and ignored.

ParametersJSON Schema
NameRequiredDescriptionDefault
production_nameNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/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 reveals the underlying method call and parameter behavior, but does not describe error cases or what happens if no changes are pending.

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 immediately convey purpose and key details; 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 one parameter and an output schema, the description covers core behavior and parameter meaning; could add more on return values or error handling but is sufficient for a simple 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% coverage with one parameter (production_name) lacking description. Description clarifies that it is reserved and ignored, adding 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?

Clearly states it applies pending configuration changes to the running production, using specific verb and resource, and distinguishes from sibling tools like start_production or stop_production.

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?

Indicates when to use (apply pending changes), notes that only active production is updated and production_name is ignored, but does not explicitly mention when not to use or alternatives.

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

update_production_item_settingsA

Update (or create) one or more setting overrides on an existing Business Host inside a production.

For each (name, value) entry in settings:

  • if the host already has an override with that Name and Target, its Value is overwritten;

  • otherwise a new Ens.Config.Setting is appended with the given Target.

The production is then persisted with SaveToClass + %Save. To make the changes take effect on a running production without a full restart, call update_production afterwards (equivalent to clicking "Update" in the Management Portal).

ParametersJSON Schema
NameRequiredDescriptionDefault
config_nameYesConfig name of the Business Host (Service / Process / Operation) to modify.
settingsYesDict of `{SettingName: value}` pairs to apply. Values are coerced to strings before being stored.
production_nameNoProduction class name. If empty, the active production is used.
targetNoSetting target context, either `"Host"` (default) or `"Adapter"`. Applied to every entry in this batch.Host

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.9/5.0
Behavior5/5

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

With no annotations, the description fully bears the transparency burden. It discloses persistence method (SaveToClass + %Save), creation behavior, string coercion, and the need for a separate update step.

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 with clear sections. Concise yet comprehensive, front-loading the main action and using efficient phrasing.

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 all necessary context: purpose, behavior, persistence, and post-step. Output schema exists, so return values need no description.

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

Parameters4/5

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

Schema coverage is 100% (baseline 3). The description adds value by explaining settings overwrite/append logic and the target parameter's effect, plus string coercion 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 explicitly states the tool updates or creates setting overrides on a Business Host, using clear verbs and specifying the resource. It distinguishes from siblings like add_production_item and update_production.

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 guidance: describes when to use (to modify settings), explains behavior for existing vs new overrides, and instructs to call update_production afterwards for running productions.

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. Dates show when Glama detected each change.

  1. 26 tool updatesv0.1.4
    • First observedadd_production_item
    • First observedcheck_global
    • First observedcheck_global_content
    • First observedcreate_empty_production
    • First observedcreate_index
    • First observeddescribe_table
    • First observedexport_table
    • First observedfetch_data
    • First observedget_active_production
    • First observedget_class_source
    • First observedget_production_item_settings
    • First observedget_tables
    • First observedimport_csv_to_iris
    • First observedinsert_data
    • First observedlist_global_subscripts
    • First observedlist_production_items
    • First observedregister_web_application
    • First observedremove_production_item
    • First observedremove_web_application
    • First observedrun_class_method
    • First observedsave_global
    • First observedsearch_code
    • First observedstart_production
    • First observedstop_production
    • First observedupdate_production
    • First observedupdate_production_item_settings
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.2/5.0
Disambiguation4/5

Most tools have clearly distinct purposes, covering production management, database operations, globals, web apps, and code search. A few pairs like check_global/check_global_content and fetch_data/export_table could cause confusion, but descriptions help differentiate them.

Naming Consistency3/5

Naming conventions are mixed: some use verb_noun (add_production_item), others verb_object (describe_table), and some verb_phrase (import_csv_to_iris). While readable, there is no consistent pattern like verb_noun throughout, which reduces predictability.

Tool Count4/5

With 26 tools, the server covers a broad domain (production, database, globals, web apps, code). While slightly high, each tool serves a distinct purpose within the scope, making the count acceptable.

Completeness3/5

The tool set covers production lifecycle, database queries, and global management well, but lacks explicit table creation (only via import), update/delete rows, and table deletion. These gaps can hinder typical CRUD workflows and require workarounds.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • mcp-ohmy-sql

    MacHu-GWU
    -
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that bridges AI assistants with SQL databases, enabling natural language querying across multiple database types with built-in optimization and security.
    3
    -

  • ignition-mcp

    jsgorana
    A
    license
    C
    quality
    C
    maintenance
    MCP server for Inductive Automation Ignition, enabling AI assistants to browse and write tags, query history and alarms, manage projects, and deploy Perspective views through natural language.
    43
    1
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pietrodileo/iris-mcp-blueprint'

If you have feedback or need assistance with the MCP directory API, please join our Discord server