pixel-surgeon-mcp

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

No annotations, but description compensates fully: discloses file reading mechanism, model choices with tradeoffs, default model, env var override, fallback behavior, and required API keys.

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?

Front-loaded with main action. Each sentence adds value. Slightly long due to model and style details, but all are informative. No 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 6 parameters (4 with enums), no output schema, and complex model/style options, description covers all necessary context: prerequisites, model behavior, key usage notes. Complete for agent 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?

Schema coverage 100%. Description adds value: explains model param with detailed tradeoffs, style param with presets described, and clarifies default behavior for aspect_ratio when style is set.

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 'Edit an existing image', verb+resource. Distinguishes from siblings like generate_image (create new) and fix_image. Provides model options and prerequisites.

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 mentions prerequisites (use list_images or save_image first) and model tradeoffs. Implicitly separates from generation tools. No explicit when-not-to-use, but context is clear.

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

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

No annotations provided, so description carries full burden. It explains the tiling process and why smaller sections help, but does not disclose failure modes, authentication requirements, or what happens to the original file.

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 front-loading the action, rationale, and use case. Every sentence earns its place with zero 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?

No output schema, but the description covers the process and use case adequately for the tool's complexity. Could mention that the tool produces a fixed image, but not essential.

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% and schema descriptions are very detailed (e.g., model parameter includes provider tradeoffs). The main description adds little beyond repeating the tiling concept, meeting 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 uses a specific verb-reource pair ('Fix an image') and explicitly states the method (splitting into tiles, re-rendering). It distinguishes from siblings like edit_image or fix_region by focusing on garbled text and tiling approach.

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?

Directly says 'Use this when a generated image has text artifacts or overloaded text regions.' Clear context but lacks explicit when-not-to-use or alternative tool mentions beyond the implied tiling approach.

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

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

Discloses cropping and snapping to nearest aspect ratio, and model tradeoffs in parameter description. However, no annotations exist, and it omits details like destructive nature, rate limits, 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.

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

Two sentences plus parameter table; front-loaded with purpose and usage. Every part is informative, 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?

Covers purpose, when to use, and key behavioral aspects. Lacks output description and error handling, but sufficient given tool complexity and parameter clarity.

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 all parameters with descriptions (100% coverage). The description adds minimal extra beyond schema; model parameter has detailed tradeoffs within schema, so 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 it fixes a region of an image by cropping, repairing, and reinserting. Distinguishes from fix_image's grid approach, saying it's more precise for partial glitches.

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 it when only part of an image has glitched text or artifacts, and contrasts with fix_image. Provides clear when-to-use and alternative.

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

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

With no annotations provided, the description carries the full burden. It mentions the tool generates a single image and results are viewable in the browser viewer, but does not disclose any side effects, permissions, or failure modes. It is adequate but not thorough.

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

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

The main description is three short sentences that efficiently convey purpose, model support, and output availability. The style details are appropriately placed in the parameter schema, keeping the main description clean. 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?

Given the lack of annotations and output schema, the description explains what the tool does and model options, but misses behavioral details like return format, error handling, or when to choose this over siblings. Adequate for basic use but not fully complete.

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 significant value by detailing model tradeoffs (speed, quality, cost) and providing extensive style descriptions with examples. This goes beyond the schema's enum labels.

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 'Generate a single image' and specifies supported models, but does not explicitly distinguish from the sibling 'generate_images' tool, which likely generates multiple images. The mention of 'single' provides some differentiation, but it could be more explicit.

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 guidance on when to use this tool versus alternatives like 'generate_images' or other image tools. Model tradeoffs are described, but that's for choosing a parameter, not for tool selection. The description lacks usage context.

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

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

The description reveals parallel execution and that full-resolution images are viewable, but with no annotations provided, it fails to disclose authentication requirements, rate limits, error behavior, 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.

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

The description is three concise sentences, front-loaded with the core function. Every sentence adds relevant information without redundancy or filler.

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?

Despite no output schema, the description only vaguely says 'Returns the generated images and any accompanying text', omitting details like output format (URLs, base64), number of images, or any concurrency limits. This incompleteness hampers agent understanding.

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 100% schema description coverage, the schema already documents all parameters. The tool description adds minimal value beyond 'pass the model param to choose', which is a high-level remark. Baseline 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 generates multiple images in parallel, distinguishes it from the sibling 'generate_image' tool, and specifies supported models. The verb 'Generate' and resource 'multiple images' are explicit.

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 when multiple images are needed via 'Generate multiple images in parallel', but does not explicitly state when to use this tool versus alternatives like 'generate_image', nor provides when-not-to-use guidance.

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

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

Without annotations, the description reveals key behaviors: polling (1-3 minute generation), output format (MP4), ambient audio generation, and storage/viewing (shared directory, browser viewer). This is transparent, though it omits potential error scenarios or limitations.

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 four sentences, each adding value: purpose, time/polling, audio, storage. No unnecessary words, and the most critical info is front-loaded.

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?

The description covers output format, timing, and storage, which is fairly complete for a generation tool with no output schema. However, it lacks mention of file size limits, quality options, or error handling.

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%, and the description adds minimal value beyond the schema's parameter descriptions. The prompt advice is already in the schema, and aspect ratio/duration enums are clear. The baseline score of 3 is appropriate.

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

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

The description clearly states the tool generates a video using Google's Veo 3, returns an MP4 file, and distinguishes itself from sibling image tools (e.g., generate_images) by mentioning video-specific features like ambient audio and polling.

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 is for video generation, but it does not explicitly state when not to use it or provide alternatives among sibling tools. The context of sibling tools suggests image generation tools are separate, but the description lacks direct guidance.

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

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

With no annotations, the description carries the full burden. It explains the interactive workflow (opens browser tool, awaits user input, crops, repairs, composites), but lacks details on blocking behavior, timeout, or what happens if no selection is made. The core behavior is described, but some edge cases 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?

Three sentences: first states the primary action, second explains the process, third provides usage guidance. No redundant information. Well-structured and front-loaded.

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?

The description covers the interactive process and the compositing outcome. However, it does not explicitly state what the tool returns (e.g., the final image path or object). Given the complexity and absence of output schema, a brief mention of return value would improve 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?

Schema coverage is 100%, so the description does not need to add much. It does not elaborate on parameters beyond what the schema already provides. The model parameter has extensive enum descriptions in the schema itself. Description adds little new meaning, 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.

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

The description clearly specifies the action: opens a browser-based crop tool, waits for user to draw a rectangle, then repairs and composites. It distinguishes itself from sibling tools like 'fix_image' by emphasizing interactive, user-guided precision.

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 states 'Best for precise, user-guided fixes' which implies when to use, but it does not explicitly mention when not to use or provide direct comparisons to sibling tools like 'fix_region' or 'fix_image'. The usage guidance is implied rather than explicit.

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

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

No annotations are provided, so the description carries full burden. It discloses the directory and purpose, but does not mention any behavioral traits like sorting, filtering, or read-only nature. Slightly lacking for a zero-annotation tool.

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 no wasted words. The information is front-loaded and 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 (no parameters, no output schema), the description is complete enough. It explains what the tool does and its intended use, fitting the context of sibling tools.

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 zero parameters, so schema covers everything. The description adds the directory path and purpose, adding value beyond the empty schema. Baseline for 0 params is 4.

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 image and video files in a specific directory, using the verb 'list' and specifying the resource. It differentiates from sibling tools which are editing/generation operations.

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 says 'Use this to find images available for editing,' implying usage before editing tools. While it doesn't explicitly state when not to use, the sibling context provides sufficient differentiation.

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

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

With no annotations, the description must carry the full burden. It discloses the output format (PNG with alpha) and the prerequisite file location, but lacks detail on behavior when the target color is not present or the effect of the threshold parameter beyond the schema.

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

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

The description is extremely concise with two sentences, front-loading the purpose and output format in the first sentence and the usage prerequisite in the second. 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?

For a tool with 3 parameters, no output schema, and no annotations, the description covers the core functionality, output, and a key prerequisite. Minor gaps exist (e.g., handling of missing color, edge cases), but it is largely complete for the task.

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 baseline is 3. The description adds no parameter-specific details beyond what the schema provides; all parameters are already described in the schema with defaults and ranges.

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 purpose: remove a background color and make it transparent, outputting a PNG with alpha channel. It distinctly differentiates from sibling tools like edit_image or fix_image, which do not specialize in background removal.

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 states that the image must already exist in a specific directory and recommends using save_image first, providing clear contextual guidance. However, it does not mention when not to use this tool or alternatives.

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

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

No annotations provided; description discloses the copy operation but lacks details on permissions, side effects, or limitations. Adequate for a simple non-destructive action.

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 wasted words. Front-loaded with the action and purpose, then usage condition.

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 tool with one parameter and no output schema, the description covers purpose, usage, and parameter sufficiently.

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 the parameter with a description ('Absolute path to the image file to import'); the tool description does not add further meaning. Baseline 3 due to high schema coverage.

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 ('Copy an image file') and the specific resource (shared pixel-surgeon directory), and distinguishes from sibling tools by indicating this is a prerequisite for editing.

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 says when to use this tool: 'when the user wants to edit an image that exists elsewhere on their filesystem.' While it doesn't say when not to use it or list alternatives, 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.

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

No annotations provided, so description carries full burden. It explains the underlying technique (potrace) and mentions key parameters, but does not disclose output details (e.g., file path, name convention) or limitations (e.g., unsupported image types).

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: one describing the action and ideal usage, one providing a critical prerequisite. 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?

No output schema is provided, and the description does not specify what the output is (e.g., saved SVG file path). For a conversion tool, this is a notable gap, but the description is otherwise sufficient for basic use.

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% and schema descriptions fully document each parameter. The description adds no additional semantics 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?

Clearly states the tool converts a raster image to SVG using potrace, and specifies best use cases (line art, diagrams, logos, high-contrast images). However, it does not explicitly differentiate from sibling tools like save_image or edit_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?

Provides context on when the tool is best used (line art, etc.) and includes a essential prerequisite: the image must exist in /root/Pictures/pixel-surgeon via save_image. Lacks explicit 'when not to use' instructions.

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