This server is an MCP bridge that gives AI assistants hands inside Fiji/ImageJ for inspecting, driving, and verifying image-analysis work.
Inspect the environment: health check, Fiji path/mode/version, open image windows, image dimensions/ROI stats, command listings, and extension/update-site info.
Find and understand plugins: search commands by keyword, list all commands, and get detailed parameter metadata for SciJava plugins.
Run code: execute ImageJ1 macro code, run batches of macros, and orchestrate scripted workflows with optional per-step verification.
Work with images: open images from disk, save the active image with a format hint, list open images, and read detailed image metadata.
Verify visually: capture screenshots of the full screen, active image, or Results table, and compare before/after images using MAE, RMSE, and a side-by-side diff image.
Parse output: turn macro return text or Results snippets into structured JSON, key/value maps, tabular rows, or extracted numbers.
Use bundled templates: list and fetch reusable macro snippets for filtering, segmentation, channels, stacks, and other common tasks.
Track activity: view a session trace of recent tool calls and open-image state, and clear the trace when needed.
Allows AI agents to control Fiji/ImageJ for microscopy image analysis, including opening images, applying filters, thresholding, particle analysis, skeletonization, and running macros.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Fiji MCP Server Apply a Gaussian blur with sigma 4 and show me the result."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Give your AI assistant hands inside Fiji/ImageJ. Fiji MCP Server is a small stdio Model Context Protocol bridge that can open and save images, discover and run installed commands, execute IJM or Groovy, read Results, and verify changes with screenshots.
This README documents v0.2.0. The public surface is deliberately limited to nine tools; Fiji's live command registries and scripting APIs provide the plugin reach without a large custom framework.
You need Python 3.10 or newer and a local Fiji installation.
Install the server:
python -m pip install "fiji-mcp-server==0.2.0"To test a source checkout instead:
python -m pip install .Locate the Fiji root directory. It must directly contain jars/ and
plugins/; on this Mac, for example, it is /Applications/Fiji.
Configure your MCP client with FIJI_PATH and FIJI_MODE=headless; see
the client-specific instructions below. The MCP client owns the stdio process
and starts fiji-mcp-server when needed.
Fiji starts lazily on the first Fiji-backed tool call. The bridge prefers one compatible JVM bundled inside the selected Fiji installation.
Related MCP server: Cellpose MCP Server
The official Codex CLI, IDE extension, and ChatGPT desktop app share MCP configuration on the same Codex host. Add this stdio server from a terminal:
codex mcp add fiji \
--env FIJI_PATH=/Applications/Fiji \
--env FIJI_MODE=headless \
-- fiji-mcp-server
codex mcp listOr add the equivalent entry to ~/.codex/config.toml (or a trusted project's
.codex/config.toml):
[mcp_servers.fiji]
command = "fiji-mcp-server"
startup_timeout_sec = 120
tool_timeout_sec = 300
[mcp_servers.fiji.env]
FIJI_PATH = "/Applications/Fiji"
FIJI_MODE = "headless"In ChatGPT desktop, you can also open Settings → MCP servers → Add server, choose STDIO, and then restart after saving. See the official Codex MCP documentation for current client controls.
For Claude Code, use the absolute path reported by which fiji-mcp-server:
claude mcp add \
--scope user \
--transport stdio \
fiji \
--env FIJI_PATH=/Applications/Fiji \
--env FIJI_MODE=headless \
-- /absolute/path/to/fiji-mcp-server
claude mcp get fijiFor Claude Desktop, add this entry to claude_desktop_config.json. On macOS,
the file is in ~/Library/Application Support/Claude/. On Windows, it is in
%APPDATA%\Claude\. Fully quit and reopen Claude Desktop after saving.
{
"mcpServers": {
"fiji": {
"command": "/absolute/path/to/fiji-mcp-server",
"args": [],
"env": {
"FIJI_PATH": "/Applications/Fiji",
"FIJI_MODE": "headless"
}
}
}
}See the official Claude Code MCP guide and Claude Desktop host guide.
Gemini CLI supports the same local stdio server. User scope makes it available in all trusted projects:
gemini mcp add \
--scope user \
--transport stdio \
-e FIJI_PATH=/Applications/Fiji \
-e FIJI_MODE=headless \
fiji /absolute/path/to/fiji-mcp-server
gemini mcp listSee the official Gemini CLI MCP guide.
Local MCP is currently documented for the Perplexity macOS app from the Mac
App Store. The feature is rolling out to paid subscribers. Open Settings →
Connectors, install the PerplexityXPC helper, then select Add Connector
→ Simple. Use Fiji as the server name and this command:
/usr/bin/env FIJI_PATH=/Applications/Fiji FIJI_MODE=headless /absolute/path/to/fiji-mcp-serverSave the connector, wait for Running, and enable it under Sources. Perplexity does not currently document local MCP setup for Windows or standalone Comet. See the official Perplexity local MCP guide.
Prompt: Open
/data/cells.tif, inspect its dimensions and current C/Z/T position, and show me an active-image screenshot.
Prompt: Search the installed Fiji commands for “Gaussian Blur”. Show the best matching command's invocation route and accepted inputs, then run it with sigma 2 only if that parameter is supported.
Prompt: Run an ImageJ macro that thresholds the active image and measures it, then return the Results table in pages of 200 rows.
Prompt: Save a screenshot to
/tmp/before.png, apply the chosen threshold, save/tmp/after.png, and compare them. If the expected change is absent, inspect state and logs before adjusting the threshold once; do not blindly repeat a mutation whose outcome is unknown.
Prompt: Use Groovy to call an installed scriptable plugin that is not representable as a structured command, then summarize its bounded result and the active-image state.
Prompt: Save the active image as
/data/output/processed.tiff. Do not overwrite an existing file, and report the exact path Fiji created.
Inspect and move data: read live state, open a local image, save the active image, and page through the Results table.
Use installed commands: search Fiji's SciJava and ImageJ1 registries, then invoke a selected command through structured parameters or legacy options when that route is supported.
Reach scriptable plugins: use trusted IJM or Groovy for ROIs, unusual Java inputs, and installed plugins that do not fit the registered command route.
Verify visually: render the active plane or Results table, save before and after PNGs, and compare dimensions and same-size pixel metrics.
The server does not install plugins, click dialogs, drive menus, or promise structured parameters for every plugin.
Tool | Purpose |
| Read Fiji lifecycle, active/open images, and Results-table state. |
| Search registered SciJava and ImageJ1 commands and inspect their routes. |
| Run one resolved installed command with supported parameters or options. |
| Run one trusted IJM or Groovy script. |
| Open an existing local image and make it current. |
| Save the active image to a new exact lowercase supported path. |
| Read an ordered, paginated page from Fiji's live Results table. |
| Return and optionally save a PNG of the active plane or Results. |
| Compare two saved raster paths visually and, when sizes match, numerically. |
See the complete nine-tool reference for signatures, return fields, limits, and failure behavior.
AI client ── stdio JSON-RPC ──▶ FastMCP ── serialized bridge ──▶ PyImageJ ──▶ Fiji + installed pluginsFiji operations share one process-wide lock. Read-only operations receive at most one retry for a small allowlist of transient failures. Commands, scripts, image opens, and saves are never automatically repeated after dispatch.
run_script executes trusted arbitrary local code. IJM and Groovy can read
or modify anything available to the MCP process, so run this server only for a
trusted local client. It is not a remote multi-user service or a sandbox.
Python diagnostics and ordinary Java output are redirected to stderr to protect
stdio JSON-RPC. Plugins that require GUI dialogs, mouse/keyboard automation, or
unscriptable interaction may fail in headless mode. Use FIJI_MODE=gui only for
an intentional local desktop workflow supported by that plugin.
save_image is strict within this MCP server process: its requested suffix must
be one of the exact lowercase formats documented in the tool reference, and an
output that exists when the serialized save begins is rejected. It is not a
cross-process atomic publisher, so another local process can still race that
check; use a dedicated output directory when other writers are active.
screenshot and compare_screenshots overwrite an existing save_path; use a
new path when preserving an existing PNG is required. After any mutation with
an unknown outcome, inspect state or take a screenshot before deciding whether
to retry.
README-structure inspiration: Cellpose MCP
Related minimal viewer bridge: napari-mcp
BSD-3-Clause. See LICENSE.
Clear the in-process session trace (does not close Fiji images).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | No | |
| cleared | Yes | Number of trace rows removed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'clear' which is a mutating action, but annotations declare readOnlyHint=true and idempotentHint=true, creating a contradiction. The description does not resolve this inconsistency; it fails to accurately reflect the behavioral safety profile intended by the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately states the action and adds a clarifying negation. It is concise, front-loaded, and contains no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and presence of output schema and annotations, the description adequately covers the tool's core function and adds context about not closing images. However, the contradiction with annotations reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description does not need to add parameter semantics. Schema coverage is 100%, and the description is sufficiently clear for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool clears the in-process session trace and explicitly clarifies it does not close images, distinguishing it from potential confusion with image operations. The purpose is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description implies usage for clearing traces, it provides no explicit guidance on when to use this tool versus alternatives (e.g., get_session_trace) or any prerequisites. The lack of parameters simplifies usage, but guidelines are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two screenshot_fiji payloads (before/after). Returns mean absolute error and RMSE on aligned grayscale patches plus a side-by-side JPEG for quick visual diff.
| Name | Required | Description | Default |
|---|---|---|---|
| image_base64_before | Yes | image_base64 from an earlier screenshot_fiji call (before step). | |
| image_base64_after | Yes | image_base64 from screenshot_fiji after the operation. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| mime_type | Yes | |
| format | Yes | |
| width | Yes | |
| height | Yes | |
| image_base64 | Yes | |
| mean_abs_error | Yes | |
| rmse | Yes | |
| width_before | Yes | |
| height_before | Yes | |
| width_after | Yes | |
| height_after | Yes | |
| compare_width | Yes | |
| compare_height | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral details: it compares on aligned grayscale patches and returns a JPEG. There is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence that front-loads the purpose and lists outputs without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameters and existing output schema, the description is mostly complete. It explains outputs well but misses mention of automatic alignment or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The description reiterates that the parameters come from screenshot_fiji payloads, but adds no new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares two screenshot payloads (before/after) and specifies the outputs: mean absolute error, RMSE, and a side-by-side JPEG. It is a specific verb-resource combination that distinguishes itself from sibling tools like screenshot_fiji.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used after capturing screenshots, providing clear context. However, it does not explicitly state when not to use it or mention alternatives, though no direct alternative exists among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve one command by name and return SciJava input metadata when available. Legacy ImageJ1-only plugins may omit inputs; use run_macro in that case.
| Name | Required | Description | Default |
|---|---|---|---|
| command_name | Yes | Command or plugin title as shown in Fiji (exact or partial match). |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| command | Yes | Matched command record. |
| inputs | Yes | Declared inputs when CommandService exposes them. |
| inputs_available | Yes | True if any input metadata was returned. |
| note | Yes | Guidance when metadata is incomplete (legacy plugins). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only and idempotent. The description adds context that metadata is returned only when available and that legacy plugins may lack inputs, providing further behavioral insight beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The first sentence states the core purpose, the second adds critical usage guidance. Every part earns its place, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one fully documented parameter, existing annotations, and an output schema (implied by 'has output schema'), the description covers the essential context: what it does, when to avoid it, and what it returns. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameter command_name is already well-documented. The description only minimally adds meaning by implying the command is resolved by name, which overlaps with the schema description. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves a command by name and returns SciJava input metadata, which is a specific verb+resource. It also distinguishes from the sibling tool run_macro for legacy plugins, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to use run_macro instead for legacy ImageJ1-only plugins that may omit inputs, providing clear when-to-use and when-not-to-use guidance relative to an alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read dimensions, channel/frame/slice counts, bit depth, and ROI statistics for one image. Uses the front image when image_title is omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| image_title | No |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| title | Yes | |
| width | Yes | |
| height | Yes | |
| slices | Yes | |
| frames | Yes | |
| channels | Yes | |
| bit_depth | Yes | |
| mean | Yes | |
| std_dev | Yes | |
| min | Yes | |
| max | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description does not need to reiterate safety. It adds value by specifying the default behavior of using the front image when omitted, which is a behavioral trait beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no extraneous information. The first sentence lists the output attributes, the second provides parameter guidance. Everything is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (one optional parameter, annotations for safety, and an output schema), the description covers the essential aspects: what is returned and how to specify the image. No additional information is necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates by explaining the default behavior for the single parameter ('uses the front image when image_title is omitted'). However, it does not describe the parameter's type or accepted values (e.g., exact window title string), relying on the schema which contains a description but is not counted. This provides marginal additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read dimensions, channel/frame/slice counts, bit depth, and ROI statistics for one image.' This is a specific verb+resource combination that distinguishes it from siblings like list_open_images (which lists image titles) by focusing on detailed metadata of a single image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Uses the front image when image_title is omitted,' which gives a clear default behavior and context. However, it does not explicitly state when not to use this tool or mention alternatives like search_commands or list_open_images, though the purpose implicitly distinguishes it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch one bundled macro template by id (from list_macro_templates).
| Name | Required | Description | Default |
|---|---|---|---|
| template_id | Yes | Stable id, e.g. gaussian_blur, analyze_particles. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| template | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, indicating a safe, side-effect-free operation. The description adds no further behavioral traits, but with annotations present, this is adequate. A higher score would require additional disclosures (e.g., errors, permissions).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately conveys the action and resource. No filler or redundant information. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, full annotations, output schema exists), the description is fully sufficient. It references the companion sibling tool and covers the core purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 adds only 'by id', which does not significantly enhance the schema's parameter description ('Stable id, e.g. gaussian_blur, analyze_particles'). No extra semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Fetch', the resource 'bundled macro template by id', and references the sibling tool 'list_macro_templates' to provide context and differentiate from listing all templates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a usage order: first call list_macro_templates to get ids, then use this tool with a specific id. It does not explicitly state when not to use it or list alternatives, but the context is sufficient for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return recent tool invocations (run_macro, open_image, …) in order plus optional live open-image list. Trace is in-process only (resets when the MCP server restarts).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max recent events to return. | |
| include_open_images | No | If true, append current open-image windows (same data as list_open_images; no extra trace row). |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| returned_events | Yes | |
| events | No | |
| open_images | No | Snapshot of open windows when include_open_images was true. |
| note | No | Non-fatal issues (e.g. open-image snapshot failed). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint. Description adds value by disclosing that trace is in-process only and resets on server restart, and clarifies that include_open_images appends current windows without adding an extra trace row. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with front-loaded key information. Each sentence adds essential context without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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, description need not explain return values. Parameters are fully covered, and behavioral constraints (in-process only) are stated. No gaps in completeness for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. Description adds context: limit is 'Max recent events to return' (redundant but clear), and include_open_images notes it shares data with list_open_images and does not add a new row, enhancing understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Return recent tool invocations' with specific examples like run_macro and open_image, and mentions optional live open-image list. It distinguishes itself from siblings by noting that include_open_images provides same data as list_open_images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for debugging or monitoring recent actions but does not explicitly state when to use vs alternatives. It mentions the in-process limitation which is a usage constraint, but no comparative guidance with siblings like clear_session_trace.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return runtime health: Fiji path, headless/GUI mode, ImageJ version, and configured operation timeout. Use before long jobs to confirm the bridge is alive.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | No | Bridge responded successfully. |
| initialized | Yes | PyImageJ context is ready. |
| fiji_path | Yes | Resolved Fiji installation path, if known. |
| mode | Yes | Runtime mode, e.g. interactive or headless. |
| imagej_version | Yes | ImageJ/Fiji version string from the Java side. |
| operation_timeout_seconds | Yes | Per-operation timeout from FIJI_OPERATION_TIMEOUT_SECONDS. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint; description adds specific return fields (Fiji path, mode, version, timeout) beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with return content, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and an output schema, description fully explains purpose and usage; no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage is 100% and description adds no parameter info, which is appropriate given zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool returns runtime health (Fiji path, mode, version, timeout) and distinguishes from sibling tools like run_macro or open_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using before long jobs to confirm bridge is alive, providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enumerate Fiji/ImageJ commands from SciJava CommandService and legacy ij.Menus. Large installs return thousands of entries; lower limit for faster responses.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of commands or matches to return. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| total | Yes | Total commands discovered. |
| returned | Yes | Number of commands in this response (capped by limit). |
| commands | Yes | Slice of commands up to limit. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description adds behavioral context: it enumerates from specific services and mentions performance characteristics (large installs, limit for speed). No destructive behavior is implied, consistent with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the main action ('Enumerate Fiji/ImageJ commands'), and includes essential details without redundancy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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, output schema present), the description adequately covers purpose, behavior, and parameter usage. No additional context is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for the 'limit' parameter, but the description adds meaningful context by explaining its purpose in relation to performance ('lower limit for faster responses'). This goes beyond a bare schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool enumerates Fiji/ImageJ commands from specific sources (SciJava CommandService and legacy ij.Menus), distinguishing it from sibling tools like search_commands. It also notes the potential for large results and suggests adjusting the limit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises lowering the limit for faster responses in large installs, providing implicit usage context. However, it does not explicitly state when to prefer this tool over search_commands or other alternatives, which slightly limits its guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List configured ImageJ update sites (name and URL) when the updater classes are present. May return an empty list on minimal installs; see note field.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | No | |
| extensions | Yes | |
| count | Yes | |
| note | Yes | How extension list was obtained or why it may be empty. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint. The description adds that the list may be empty on minimal installs, which is useful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action and followed by important caveats. Every sentence adds value without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, output schema exists), the description covers the key points: what it lists, precondition, edge case (empty on minimal installs), and a pointer to the note field. It is complete for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters (schema is empty), so schema description coverage is 100%. The baseline for zero parameters is 4, and the description correctly does not attempt to explain parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists configured ImageJ update sites (name and URL). It distinguishes itself from sibling listing tools like list_open_images, list_all_commands, and list_macro_templates by specifying the exact resource (update sites).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage condition: 'when the updater classes are present.' It also warns about possible empty lists on minimal installs. While it doesn't explicitly mention when not to use or compare to siblings, the precondition is helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List bundled macro snippets (filters, segmentation, Z-project, channels, optional Fiji plugins) with stable ids. Filter by category: filters, process, segment, analyze, image, annotate, channels, stack, plugins.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| count | Yes | |
| templates | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's mention of 'stable ids' adds a small behavioral insight. However, details like behavior with invalid categories or response format are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loading the purpose and immediately providing useful filter information. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations and existence of an output schema, the description is largely complete. It covers the primary function and filter option. Minor gap: no mention of response structure, but output schema likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates by listing all valid category values. It explains the filter parameter's purpose and acceptable values, though it does not specify the default behavior when omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists bundled macro snippets with stable ids, and provides a filter by category. It distinguishes from siblings like `get_macro_template` (which retrieves a specific template) and `run_macro` (which executes macros).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes filter categories, implying usage context, but does not explicitly state when to use this tool over alternatives, nor does it provide when-not-to-use guidance. The sibling tools suggest this is for browsing available templates before selecting one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List open image windows with id, title, dimensions, and ImageJ type constant.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| ok | No | |
| count | Yes | |
| images | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description adds limited behavioral context beyond listing the returned fields. No additional behavioral traits are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence (12 words) that immediately conveys the tool's action and output. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, output schema exists), the description adequately conveys the tool's purpose and output. It does not need additional detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With no parameters, schema coverage is 100%. The description does not need to add parameter meaning, and the baseline for 0 parameters is 4. The description is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 'open image windows', and specifies the returned fields (id, title, dimensions, ImageJ type constant). This differentiates it from siblings like 'get_image_info' which targets specific images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit usage guidelines are provided. The tool's purpose is straightforward, but there is no mention of when to use this versus alternatives or any preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open an image from disk in Fiji and show it as the active window. Verify the path exists on the MCP host before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute or user-expandable path to an image file Fiji can open. |
| Name | Required | Description |
|---|---|---|
| ok | No | Image opened and shown in Fiji. |
| title | Yes | Window title of the opened image. |
| width | Yes | |
| height | Yes | |
| path | Yes | Absolute path that was opened. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint: false (not read-only) and destructiveHint: false (not destructive). The description adds context about verifying path existence but does not disclose potential side effects such as changing the active window, memory usage, or handling of unsupported file formats. With the annotations already providing safety profile, the description adds some but not rich transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences, the first stating the purpose and the second providing a key usage guideline. It is front-loaded and free of extraneous information, making it efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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, output schema exists, annotations present), the description covers the main purpose and a critical precondition. However, it could better differentiate from sibling tools like 'list_open_images' or 'get_image_info', but the presence of an output schema reduces the need to explain return values. The overall completeness is high for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with a detailed description and examples for the 'path' parameter. The description adds value by instructing to verify path existence, which goes beyond the schema. This justifies a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: 'Open an image from disk in Fiji and show it as the active window.' It identifies the verb (open), resource (image), and distinguishes it from sibling tools like 'list_open_images' (which lists already open images) and 'save_image' (which writes to disk).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a precondition: 'Verify the path exists on the MCP host before calling.' However, it does not provide guidance on when to use this tool versus alternatives (e.g., if the image is already open, use 'list_open_images'), nor does it specify exclusions or alternative contexts. The guidance is minimal but present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn macro return text or a pasted Results snippet into structured JSON: detected format, key/value map, tabular rows, and/or extracted numbers. Prefer macros that return a small JSON or key=value string for best results.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Usually MacroRunResult.result or a log tail slice. | |
| format_hint | No | auto: try JSON, then ImageJ-style TSV, CSV, key=value lines, then numbers. json/csv/key_value/imagej_table/numbers_only: force a parser. | auto |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| format_detected | Yes | |
| parsed_json | No | |
| values | No | |
| rows | No | |
| numbers | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations confirm read-only and idempotent behavior. The description adds that it detects format and produces key/value maps, tabular rows, and numbers. It lacks mention of error handling for unparseable input, but overall adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with action and outputs, followed by a recommendation. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 and annotations, the description covers key behavioral aspects. It could mention limitations like large text handling, but overall it is sufficient for this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description's additional note about preferring small JSON is a minor augmentation. Baseline 3 applies as schema already documents parameters thoroughly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool converts macro return text into structured JSON, listing specific output components. It distinguishes itself from sibling tools, which are unrelated to parsing macro output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises preferring macros that return JSON or key=value for best results, providing usage context. It does not explicitly state when not to use, but the guidance is helpful and appropriate given the tool's uniqueness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run several macros in sequence. On failure, behavior depends on continue_on_error: either stop or record the error and continue. Each successful step returns the same shape as run_macro.
| Name | Required | Description | Default |
|---|---|---|---|
| macros | Yes | Ordered list of macro strings; each should be non-empty after strip(). | |
| continue_on_error | No | If true, record per-step errors and continue; if false, stop on first failure. | |
| retries_per_step | No | Retries passed to run_macro for each non-empty step. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | True only if every step succeeded. |
| total_steps | Yes | Number of macros requested. |
| completed_steps | Yes | Steps attempted before stop (may be less than total if stopped early). |
| failed_steps | Yes | Count of steps with ok=false. |
| results | Yes | Per-step outcomes in order. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses failure behavior (stop vs continue on error) and return shape consistency with run_macro. Annotations (readOnlyHint=false, destructiveHint=false) are consistent and non-contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero wasted words. It is front-loaded with the core action and efficiently covers key behaviors.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 (implied by 'returns the same shape as run_macro'), the description sufficiently explains behavior, failure modes, and step equivalence. No gaps remain for a batch execution tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. Description adds no new details beyond the schema for macros, continue_on_error, and retries_per_step, though it provides overarching context about return shape and failure handling.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs several macros in sequence, distinguishing it from run_macro. It also specifies failure behavior, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for sequential batch execution but lacks explicit guidance on when to use this vs sibling tools like run_macro or run_workflow. No when-not or alternative mention is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute ImageJ1 macro text in the current Fiji session. Returns macro return value and a tail of the ImageJ log. Prefer small, focused macros; increase timeout for heavy I/O.
| Name | Required | Description | Default |
|---|---|---|---|
| macro_code | Yes | ImageJ macro language source, e.g. run("Gaussian Blur...", "sigma=2"); | |
| retries | No | Number of retries on transient Java bridge failures (macro tools). |
| Name | Required | Description |
|---|---|---|
| ok | No | Macro finished without raising on the Java side. |
| result | Yes | String return value from ImageJ1.runMacro, often empty. |
| log_tail | Yes | Tail of the ImageJ log window (last ~4000 chars), useful for debugging. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds some behavioral context beyond annotations (return value, log tail, timeout hint) but does not disclose potential mutation or side effects, given destructiveHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each serving a distinct purpose: purpose/return and usage advice. No filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema and annotations, the description covers purpose and return but lacks details on side effects, prerequisites, or security considerations for arbitrary code execution.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with examples and default values; description adds no additional semantic value beyond restating macro_code as 'ImageJ1 macro text'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute ImageJ1 macro text in the current Fiji session' and specifies return values, effectively distinguishing from siblings like run_batch_macros and parse_macro_output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance to prefer small, focused macros and increase timeout for heavy I/O, offering clear context for usage but not explicitly contrasting with alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a scripted pipeline: each step runs a macro, optionally followed by a screenshot. Supports MCP progress when the client requests it. Use verify_each_step=false for faster runs.
| Name | Required | Description | Default |
|---|---|---|---|
| steps | Yes | Each step: {"macro", "screenshot_after", "screenshot_capture": "full_screen"|"active_image"|"results_table"}. Defaults use active_image screenshots (headless-safe); use full_screen only with GUI Fiji. | |
| verify_each_step | No | If true, append screenshot after each step when screenshot_after allows. | |
| continue_on_error | No | If false, stop after the first failing step and return partial results. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | True if every step succeeded. |
| results | No | |
| total_steps | No | Set on full completion summary. |
| failed_steps | No | Count of failed steps on full summary. |
| completed_steps | No | On early abort, number of fully completed steps before the failure. |
| failed_step | No | On early abort, 1-based index of the first hard failure. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses MCP progress support, screenshot defaults headless-safe vs GUI, adds context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no fluff, each sentence provides value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description covers purpose, key behaviors, and a parameter tip; minor gaps on prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters; description adds only a hint on verify_each_step, baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Run a scripted pipeline' with macros and screenshots, distinguishing from sibling tools like run_macro and run_batch_macros.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides 'Use verify_each_step=false for faster runs' but lacks explicit when-to-use vs 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.
Save the currently active image to disk using ImageJ's saveAs. Requires an image window to be frontmost in Fiji.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Destination path; parent directories are created if missing. | |
| format_hint | No | ImageJ saveAs format hint (tiff, png, jpeg, etc.). | tiff |
| Name | Required | Description |
|---|---|---|
| ok | No | Image written to disk. |
| path | Yes | Output file path. |
| title | Yes | Title of the image that was saved. |
| format | Yes | Format hint passed to ImageJ saveAs (e.g. tiff, png). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, describing safety profile. Description adds prerequisite about frontmost window but does not detail other behaviors (e.g., overwrite behavior, file creation). Within annotations, baseline of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with key action and prerequisite. No unnecessary words, front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple save tool with output schema, description provides purpose and prerequisite. No missing critical information given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions and examples. Description does not add significant meaning beyond schema, so baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'save the currently active image' using ImageJ's saveAs, specifying the resource and action. It distinguishes from sibling tools like open_image but does not explicitly differentiate from all possible related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states a key prerequisite: 'Requires an image window to be frontmost in Fiji', guiding when to use. Does not provide when-not-to-use or alternative tools, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture pixels for verification: full_screen (primary monitor via Robot), active_image (current ImagePlus), or results_table (render Measure/Results data). Use active_image or results_table when running headless without a display.
| Name | Required | Description | Default |
|---|---|---|---|
| capture_mode | No | full_screen: Java Robot on the primary monitor only (needs display). active_image: rasterize the current ImagePlus. results_table: render the ImageJ Results table as a PNG (no desktop; headless-friendly when data exists). | full_screen |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| capture_mode | Yes | full_screen: primary-monitor Robot capture; active_image: current ImagePlus; results_table: rendered Results window data. |
| mime_type | Yes | MIME type of the encoded image. |
| format | Yes | Encoder output format label. |
| width | Yes | |
| height | Yes | |
| from_cache | Yes | True if a recent identical capture was reused. |
| image_base64 | Yes | Base64-encoded image bytes for inline display. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes how each mode works (Robot for full_screen, rasterize for active_image, render as PNG for results_table) and notes headless limitations. No contradiction with annotations (readOnlyHint=true).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose and modes, second gives usage guidance. Front-loaded with essential information, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one enum parameter) and presence of output schema, the description covers all necessary context, including headless usage and what each mode captures.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has high coverage (100%). The description adds headless-friendly context for results_table, which goes beyond the schema, justifying a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool captures pixels for verification and lists three distinct capture modes (full_screen, active_image, results_table). It differentiates from sibling tools like compare_screenshots and get_image_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using active_image or results_table when running headless without a display, providing clear context for when to use which mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search installed commands by substring on name/class, plus fuzzy title matching. Use before describe_plugin to find the exact menu label.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Keyword to match against command titles and Java class names; fuzzy match augments results. | |
| limit | No | Maximum number of commands or matches to return. |
| Name | Required | Description |
|---|---|---|
| ok | No | |
| query | Yes | Search string used. |
| total_matches | Yes | |
| matches | Yes | Merged keyword and fuzzy matches. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral detail beyond the annotations (readOnlyHint, idempotentHint) by explaining the search logic (substring on name/class, fuzzy title). It does not contradict annotations and provides useful context about the matching behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently communicates purpose and usage. Every word adds value, and it is front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 and the tool's simplicity, the description is complete. It explains the search criteria and usage context without needing to detail return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions for both parameters (query and limit). The description adds no extra parameter information 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: searching installed commands by substring on name/class and fuzzy title matching. It distinguishes itself from siblings like list_all_commands and describe_plugin by specifying the search method and how it complements describe_plugin.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends using this tool before describe_plugin to find the exact menu label, providing clear usage context. While it does not mention when not to use it, the guidance is specific and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.3clear_session_tracecompare_screenshotsdescribe_pluginget_image_infoget_macro_templateget_session_tracehealth_checklist_all_commandslist_extensionslist_macro_templateslist_open_imagesopen_imageparse_macro_outputrun_batch_macrosrun_macrorun_workflowsave_imagescreenshot_fijisearch_commandsScored across 19 tools
Most tools have distinct purposes, e.g., run_macro vs run_batch_macros vs run_workflow are clearly differentiated by descriptions. Some related tools like describe_plugin and search_commands could cause slight confusion but are still separable.
All tool names follow a consistent verb_noun pattern using snake_case (e.g., clear_session_trace, compare_screenshots, list_open_images). No mixing of styles or ambiguous verbs.
With 19 tools, the set is well-scoped for an image processing MCP server covering session management, macro execution, image I/O, and metadata. No signs of bloat or insufficiency.
The tool surface covers core workflows: image management, macro execution, command discovery, and session tracing. Minor gaps like missing direct close_image or ROI manipulation exist but are manageable via macros.
Give your AI agents the tools to build, manage, and run automation workflows.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Create and manage AI agents that collaborate and solve problems through natural language interacti…
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
