Apache Zeppelin MCP Server

get_notebook_fingerprint

Read-onlyIdempotent

Generate a deterministic notebook fingerprint and per-paragraph sub-hashes to check if cached docs are stale; server-side comparison returns match status and exact changed paragraph IDs.

Instructions

Get a deterministic content fingerprint of a notebook, plus per-paragraph sub-hashes.

Cheap freshness check for cached notebook documentation. Only stable content is
hashed (paragraph id, title, code text); execution status, output, form
values/definitions, chart configs, and paragraph order are all excluded — none of
those flag the notebook stale.

The comparison against the cached doc happens server-side — never hand-compare
hash maps. Preferred: pass `spec_path` (the spec file under $WIKI_DOCS_PATH) and
the server reads the stored fingerprint/units from its frontmatter itself; the
response gains `"match": true|false` and `"diff": {changed, added, removed}`
naming the exact paragraph ids that differ. If the spec can't be used, the
response carries a `spec_note` explaining why and no match/diff. Fallback when
there is no docs repo: pass the stored values explicitly as `known_fingerprint` /
`known_units` (they take precedence over `spec_path` if both are given).

Args:
    notebook_id: The notebook ID to fingerprint
    spec_path: Optional path to the cached spec file inside $WIKI_DOCS_PATH
    known_fingerprint: Optional stored overall fingerprint to compare against
    known_units: Optional stored per-paragraph sub-hash map to diff against

Input Schema

Name	Required	Description	Default
`spec_path`	No
`known_units`	No
`notebook_id`	Yes
`known_fingerprint`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.1Oct 26, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description goes far beyond: it enumerates exactly which fields are hashed vs excluded (execution status, output, forms, chart configs, paragraph order) and explains that excluded fields do not flag the notebook stale. It also discloses the conditional response shape (match/diff on success, spec_note on failure) — behavior not visible in annotations.

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

Conciseness4/5

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

Front-loaded with the purpose, then usage, then argument semantics — a sensible order with no filler sentences. The trailing 'Args:' block restates the schema's parameter names, but each entry adds operational meaning, so the small redundancy is justified rather than wasteful.

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

Completeness5/5

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

For a moderately complex tool with an output schema, the description covers everything an agent needs: what is compared, where the comparison happens, the two input modes, their precedence, and the conditional return fields. Nothing required to call it correctly is left unstated.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must carry the burden — and it does, documenting all four parameters with meaning the schema cannot convey: spec_path must live under $WIKI_DOCS_PATH, known_units is a per-paragraph sub-hash map, and known_* take precedence over spec_path. This fully compensates for the bare 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?

States a specific verb+resource: 'deterministic content fingerprint of a notebook, plus per-paragraph sub-hashes'. No sibling tool does fingerprinting, and the description immediately frames it as a 'cheap freshness check', so an agent can distinguish it from get_notebook or list_paragraphs without opening the schema.

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

Usage Guidelines5/5

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

Gives an explicit decision tree: preferred path is passing spec_path (server does the comparison), fallback is explicit known_fingerprint/known_units when there is no docs repo, and it states the precedence rule if both are supplied. It also names the anti-pattern ('never hand-compare hash maps'), which is exactly the guidance an agent needs.

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