Skip to main content
Glama

fileforge_visual_action

Capture and compare page screenshots, baselines, visual diffs, and computed CSS, colors, and fonts across routes and viewports to spot visual changes.

Instructions

Capture and compare how pages look: screenshots of a page, element or region, baselines, visual diffs across routes and viewports, and computed CSS, colors and fonts. Use fileforge_responsive_action to find layout bugs. Files and baselines are saved locally. capture_screenshot needs the tab to be visible. Needs the extension.

Input Schema

NameRequiredDescriptionDefault
xNoLeft edge in pixels.
yNoTop edge in pixels.
refNoRef of a stored result.
runNoOptional run ID for grouping comparison artifacts
urlNoOptional page URL to include in metadata
nameNoBaseline namematrix
storeNoSave the result in ~/.fileforge and return a ref.
tabIdNoTab ID, or "active" for the active tab.active
widthNoWidth in pixels.
actionYesWhat to do. Required parameters are in brackets. capture_screenshot: Capture a screenshot of a tab. The tab must be the visible one in its window; otherwise the call returns TAB_NOT_VISIBLE. capture_full_page: Capture a stitched full-page screenshot of a tab and store it as a local artifact. capture_element (selector): Capture a screenshot of a specific page element by selector and store it as a local artifact. capture_region (x, y, width, height): Capture a rectangular viewport or page region and store it as a local artifact. pick_and_capture_element: Start an in-page element picker, capture the chosen element, and store it as a local artifact. capture_matrix (url): Capture a URL across multiple viewport presets and return stored screenshot artifact refs. capture_baseline (url, name): Capture and store a baseline screenshot for later comparison. capture_route_baselines (baseUrl, routes): Capture and store baseline screenshots for multiple routes and viewports. compare_screenshot (url, name): Compare the current state of a URL against its stored baseline. compare_routes (baseUrl, routes): Compare multiple routes against their baselines. extract_css (selector): Extract computed CSS for an element. extract_colors: Extract the color palette from the page. detect_fonts: Detect fonts used on the page. measure_element (selector): Measure the size and position of an element. export_diff (ref): Export a visual diff bundle as a ZIP.
activeNoFocus the tab while capturing.
formatNoOutput format.png
heightNoHeight in pixels.
routesNoRoute paths to visit, such as "/pricing".
baseUrlNoOrigin that routes are resolved against.
paddingNoExtra pixels around the element.
projectNoProject name that groups stored results.default
filenameNoOutput filename.
fullPageNoCapture the whole page, not just the viewport.
keepOpenNoLeave the tab open afterward.
selectorNoCSS selector of the target element.
settleMsNoMilliseconds to wait after load before capturing.
viewportNoOptional viewport label or dimensionsdesktop
maxHeightNoMaximum capture height in pixels.
thresholdNoPer-channel color difference to ignore. 0 counts every change.
timeoutMsNoTime limit in milliseconds.
viewportsNoViewport presets to use, such as "desktop" or "mobile".
namePrefixNoPrefix for baseline names.
scrollWaitMsNoMilliseconds to wait after each scroll.
includeBase64NoReturn the image as base64 as well as a file.
coordinateSpaceNoWhether x and y are relative to the viewport or the page.viewport
ignoreSelectorsNoCSS selectors to mask before comparing.
hideFixedElementsNoHide fixed elements while stitching the capture.

Output Schema

NameRequiredDescriptionDefault
okYesFalse if the action failed or a check did not pass.
refNoStored result ID, for fileforge_result_action.
dataNoThe result. Its shape depends on the action.
metaNoTool, action and context.
errorNoFailure code and message.
warningsNoNotes about a call that still ran.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed30 schema fields changedv0.3.0
    • changedInput schema / properties / action / description
      Previous value: -"The action to perform. Available actions: capture_screenshot: Capture a screenshot of a tab. The tab must be the visible one in its window; otherwise the call returns TAB_NOT_VISIBLE. capture_full_page: Capture a stitched full-page screenshot of a tab and store it as a local artifact. capture_element: Capture a screenshot of a specific page element by selector and store it as a local artifact. capture_region: Capture a rectangular viewport or page region and store it as a local artifact. pick_and_capture_element: Start an in-page element picker, capture the chosen element, and store it as a local artifact. capture_matrix: Capture a URL across multiple viewport presets and return stored screenshot artifact refs. capture_baseline: Capture and store a baseline screenshot for later comparison. capture_route_baselines: Capture and store baseline screenshots for multiple routes and viewports. compare_screenshot: Compare the current state of a URL against its stored baseline. compare_routes: Compare multiple routes against their baselines. extract_css: Extract computed CSS for an element. extract_colors: Extract the color palette from the page. detect_fonts: Detect fonts used on the page. measure_element: Measure the size and position of an element. export_diff: Export a visual diff bundle as a ZIP."New value: +"What to do. Required parameters are in brackets. capture_screenshot: Capture a screenshot of a tab. The tab must be the visible one in its window; otherwise the call returns TAB_NOT_VISIBLE. capture_full_page: Capture a stitched full-page screenshot of a tab and store it as a local artifact. capture_element (selector): Capture a screenshot of a specific page element by selector and store it as a local artifact. capture_region (x, y, width, height): Capture a rectangular viewport or page region and store it as a local artifact. pick_and_capture_element: Start an in-page element picker, capture the chosen element, and store it as a local artifact. capture_matrix (url): Capture a URL across multiple viewport presets and return stored screenshot artifact refs. capture_baseline (url, name): Capture and store a baseline screenshot for later comparison. capture_route_baselines (baseUrl, routes): Capture and store baseline screenshots for multiple routes and viewports. compare_screenshot (url, name): Compare the current state of a URL against its stored baseline. compare_routes (baseUrl, routes): Compare multiple routes against their baselines. extract_css (selector): Extract computed CSS for an element. extract_colors: Extract the color palette from the page. detect_fonts: Detect fonts used on the page. measure_element (selector): Measure the size and position of an element. export_diff (ref): Export a visual diff bundle as a ZIP."
    • addedInput schema / properties / active / description
      Added value: +"Focus the tab while capturing."
    • addedInput schema / properties / baseUrl / description
      Added value: +"Origin that routes are resolved against."
    • addedInput schema / properties / coordinateSpace / description
      Added value: +"Whether x and y are relative to the viewport or the page."
    • addedInput schema / properties / filename / description
      Added value: +"Output filename."
    • addedInput schema / properties / format / description
      Added value: +"Output format."
    • addedInput schema / properties / fullPage / description
      Added value: +"Capture the whole page, not just the viewport."
    • addedInput schema / properties / height / description
      Added value: +"Height in pixels."
    • addedInput schema / properties / hideFixedElements / description
      Added value: +"Hide fixed elements while stitching the capture."
    • addedInput schema / properties / ignoreSelectors / description
      Added value: +"CSS selectors to mask before comparing."
    • addedInput schema / properties / includeBase64 / description
      Added value: +"Return the image as base64 as well as a file."
    • addedInput schema / properties / keepOpen / description
      Added value: +"Leave the tab open afterward."
    • addedInput schema / properties / maxHeight / description
      Added value: +"Maximum capture height in pixels."
    • addedInput schema / properties / namePrefix / description
      Added value: +"Prefix for baseline names."
    • addedInput schema / properties / padding / description
      Added value: +"Extra pixels around the element."
    • addedInput schema / properties / project / description
      Added value: +"Project name that groups stored results."
    • addedInput schema / properties / ref / description
      Added value: +"Ref of a stored result."
    • addedInput schema / properties / routes / description
      Added value: +"Route paths to visit, such as \"/pricing\"."
    • addedInput schema / properties / scrollWaitMs / description
      Added value: +"Milliseconds to wait after each scroll."
    • addedInput schema / properties / selector / description
      Added value: +"CSS selector of the target element."
    • addedInput schema / properties / settleMs / description
      Added value: +"Milliseconds to wait after load before capturing."
    • addedInput schema / properties / store / description
      Added value: +"Save the result in ~/.fileforge and return a ref."
    • addedInput schema / properties / tabId / description
      Added value: +"Tab ID, or \"active\" for the active tab."
    • addedInput schema / properties / threshold / description
      Added value: +"Per-channel color difference to ignore. 0 counts every change."
    • addedInput schema / properties / timeoutMs / description
      Added value: +"Time limit in milliseconds."
    • addedInput schema / properties / viewports / description
      Added value: +"Viewport presets to use, such as \"desktop\" or \"mobile\"."
    • addedInput schema / properties / width / description
      Added value: +"Width in pixels."
    • addedInput schema / properties / x / description
      Added value: +"Left edge in pixels."
    • addedInput schema / properties / y / description
      Added value: +"Top edge in pixels."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "description": "query_* actions return their modules as extra top-level fields.",
      +  "properties": {
      +    "data": {
      +      "description": "The result. Its shape depends on the action."
      +    },
      +    "error": {
      +      "description": "Failure code and message."
      +    },
      +    "meta": {
      +      "description": "Tool, action and context."
      +    },
      +    "ok": {
      +      "description": "False if the action failed or a check did not pass.",
      +      "type": "boolean"
      +    },
      +    "ref": {
      +      "description": "Stored result ID, for fileforge_result_action."
      +    },
      +    "warnings": {
      +      "description": "Notes about a call that still ran."
      +    }
      +  },
      +  "required": [
      +    "ok"
      +  ],
      +  "type": "object"
      +}
  2. First observedv0.2.1

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false and openWorldHint=true, but the description adds real behavior the schema does not: results and baselines persist locally, and capture_screenshot fails with TAB_NOT_VISIBLE unless the tab is the visible one. The extension prerequisite is also a deployment constraint an agent needs. Remaining gaps are minor (no mention of how baselines are overwritten or reset), so a 4 rather than a 5.

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

Conciseness4/5

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

Four sentences, front-loaded with the capability list before the routing hint and the preconditions. The opening capability list is dense but each item maps to a distinct action family. Slightly tighter phrasing could fold the persistence and extension notices into one line, but nothing is filler.

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

Completeness4/5

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

For a 33-parameter, 15-action tool with an output schema and full schema coverage, the description supplies the things structured fields cannot: local persistence, extension dependency, the TAB_NOT_VISIBLE failure mode, and the sibling routing hint. It is close to complete; only per-action selection guidance (which action for which visual goal) is left implicit.

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

Parameters5/5

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

Schema description coverage is 100% and every one of the 33 parameters carries its own description, including the action enum which documents each of the 15 actions with its required bracketed parameters and per-action caveats. The prose description correctly does not duplicate this; the structured data carries the full semantic load, so the high baseline is warranted.

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

Purpose4/5

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

The description opens with a specific verb+resource pair ("Capture and compare how pages look") and enumerates the concrete artifacts: screenshots of page/element/region, baselines, visual diffs, computed CSS, colors, fonts. An agent can tell this is the visual/perceptual tool versus a DOM-interaction tool. It stops short of distinguishing itself from plausible visual siblings such as fileforge_eye_action or fileforge_browser_action, which keeps it from a 5.

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

Usage Guidelines4/5

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

It routes one clear case to an alternative: "Use fileforge_responsive_action to find layout bugs," establishing a boundary between visual capture/compare and responsive diagnostics. It also states two hard preconditions (tab must be visible for capture_screenshot, extension required). It gives no explicit when-not guidance for the compare/export actions, so it is context-rich but not a full decision rule.

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