Apache Zeppelin MCP Server

run_paragraph

Execute a paragraph in a Zeppelin notebook and retrieve its output, preserving chart settings; control table row limits and HTML inclusion to manage token usage.

Instructions

Run a paragraph and return the result. Uses the async job endpoint which preserves chart/visualization settings.

By default, table output is limited to 50 rows and HTML output is omitted to save tokens.
Set max_rows=0 for unlimited rows when you need full results for analysis.
Set include_html=True to see HTML output converted to plain text.

On error, the response includes the error output — examine it before retrying.

Args:
    notebook_id: The notebook ID containing the paragraph
    paragraph_id: The paragraph ID to run
    params: Optional dict of dynamic form values, e.g. {"city": "Seoul"}.
    max_rows: Maximum data rows for table output (default 50, 0 = unlimited). Header row always included.
    include_html: If True, include HTML output converted to plain text. If False (default), HTML is omitted.

Input Schema

Name	Required	Description	Default
`params`	No
`max_rows`	No
`notebook_id`	Yes
`include_html`	No
`paragraph_id`	Yes

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.1Oct 26, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations only declare the non-read-only, non-idempotent, non-destructive profile; the description goes well beyond that by disclosing token-saving truncation defaults (50 rows, HTML omitted), the header-row guarantee, the async-endpoint behavior, and crucially that errors return error output that should be examined before retrying. It stops short of noting that executing a paragraph may have side effects on notebook data or what permissions are required.

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

Conciseness4/5

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

Front-loaded with purpose followed by a clean Args block, and every sentence carries information. The only waste is mild duplication: the max_rows/include_html behavior is explained once in prose and again in the Args block, and the 'On error' note is buried mid-paragraph rather than surfaced.

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?

An output schema exists, so return-value explanation is correctly omitted, and the truncation/error behavior is covered. The remaining gap is routing: with 30+ siblings including several run variants, the definition doesn't help an agent decide that this is the right execution tool for a single paragraph.

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

Parameters5/5

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

Schema description coverage is 0%, so the description carries the full burden and does so: every one of the five parameters is documented in the Args block, including the non-obvious semantics of max_rows (default 50, 0 = unlimited, header always included) and include_html (converted to plain text), plus a concrete example for the dynamic params dict.

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?

States a specific verb+resource ('Run a paragraph and return the result') and adds real scope information: it uses the async job endpoint and preserves chart/visualization settings. However, it never distinguishes itself from close siblings like run_paragraph_async, batch_run_paragraph, or run_all_paragraphs, which is especially confusing given it claims to use the 'async job endpoint'.

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?

It gives good conditional guidance for parameters ('Set max_rows=0 for unlimited rows when you need full results for analysis', 'Set include_html=True to see HTML output'), which implies usage contexts. But it says nothing about when to choose this tool over the many sibling run/status tools, leaving the core selection decision to inference.

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