Skip to main content
Glama
axivo

Safari MCP Server

by axivo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Safari MCP Server

License: BSD 3-Clause npm Socket Node.js TypeScript

A MCP (Model Context Protocol) server for visual web access through Safari.

Features

  • Visual Web Access: Viewport screenshots for visual inspection

  • Full Authentication State: Operates on the user's actual Safari session with cookies preserved

  • Tab-Aware Targeting: Act operations target a captured working tab, observe operations follow the user's focus

  • Viewport Scrolling: Pixel amount or viewport-page index

  • Element Inspection: Tag, visibility, attributes, bounding rect for any CSS selector

  • Interaction Tools: Click, type, hover, select option

  • Wait Conditions: Selector to appear, disappear, or page text to render

  • Link Extraction: Anchor links as { text, href } pairs

  • Browser History: Back and forward navigation

  • Console Error Capture: Two-phase injection during and after page load

Prerequisites

  • macOS → System Settings → Desktop & Dock → Windows → "Prefer tabs when opening documents" option must be set to Always

  • macOS → System Settings → Privacy & Security → Screen & System Audio Recording → Terminal app must be enabled

  • Safari → Settings → Developer → Automation → "Allow JavaScript from Apple Events" option must be enabled

MCP Server Configuration

Add to mcp.json servers configuration:

{
  "mcpServers": {
    "safari": {
      "command": "npx",
      "args": ["-y", "@axivo/mcp-safari"],
      "env": {
        "SAFARI_WINDOW_HEIGHT": "1600"
      }
    }
  }
}

Environment Variables

All variables are optional:

  • SAFARI_PAGE_TIMEOUT - Page load and selector wait timeout, in milliseconds (default: 10000)

  • SAFARI_WINDOW_BOUNDS - Browser window margin offset from top-left corner, in pixels (default: 20)

  • SAFARI_WINDOW_HEIGHT - Browser window height, in pixels (default: 1024)

  • SAFARI_WINDOW_WIDTH - Browser window width, in pixels (default: 1280)

Prompt Examples

  • "Open Safari and use status tool for guidelines"

  • "Navigate to example.com"

  • "Search for example query"

  • "Take a screenshot of the current page"

  • "Read the page content to understand what's on the page"

  • "Click the 'Sign In' button"

  • "Type my email into the login form and submit"

  • "Refresh the page to see the latest changes"

  • "Go back to the previous page"

  • "Navigate forward two steps in browser history"

  • "Scroll down 500 pixels"

  • "Scroll to page 3 of this article"

  • "Search for 'Claude AI' and click the first result"

  • "List all open browser tabs"

  • "Open a new browser tab and go to example.com"

  • "Switch to the first browser tab"

  • "Close the second browser tab"

  • "Inspect the submit button before clicking it"

  • "Hover over the Products menu"

  • "Choose 'Canada' in the country dropdown"

  • "Wait for the loading spinner to disappear"

  • "Read all links on this page"

NOTE

The "use status tool" instruction helps Claude pause and process the _meta.usage guidelines before interacting with the browser.

MCP Tools

Call status first at session start to get the runtime state and full tool surface:

  • Act tools target a captured working tab

  • Observe tools target the front window's current tab

  1. click

    • Click an element on the working tab

    • Type: act tool

    • Optional inputs:

      • key (string): Key to press (e.g., Escape, ArrowRight, Enter, Tab)

      • selector (string): CSS selector for the target element

      • text (string): Visible text or aria-label to match

      • wait (string): CSS selector to wait for after click

      • x (number): X coordinate in pixels

      • y (number): Y coordinate in pixels

    • Returns: Result with change detection

  2. close

    • Close the working tab

    • Type: act tool

  3. execute

    • Execute JavaScript in the working tab

    • Type: act tool

    • Required inputs:

      • script (string): JavaScript code

  4. hover

    • Dispatch hover events to reveal hover-triggered UI

    • Type: act tool

    • Optional inputs (one is required):

      • selector (string): CSS selector for the target element

      • text (string): Visible text to match

  5. inspect

    • Return element metadata for a CSS selector

    • Type: observe tool

    • Required inputs:

      • selector (string): CSS selector for the target element

    • Optional inputs:

      • index (number): Tab index in the front window

    • Returns: { found, tag, text, visible, disabled, attributes, rect }

  6. navigate

    • Navigate the working tab to a URL or through history

    • Type: act tool

    • Optional inputs (url or direction required):

      • direction (string: back or forward)

      • selector (string): CSS selector to wait for after load

      • steps (number, default: 1): Steps for history navigation

      • url (string): URL to navigate to

  7. open

    • Open a blank tab as the working target

    • Type: act tool

  8. read

    • Get page title, URL, and text or links from a tab

    • Type: observe tool

    • Optional inputs:

      • index (number): Tab index in the front window

      • mode (string: text or links, default: text)

      • selector (string): CSS selector to scope extraction

  9. refresh

    • Refresh the working tab

    • Type: act tool

    • Optional inputs:

      • hard (boolean, default: false): Bypass cache

      • selector (string): CSS selector to wait for after reload

  10. screenshot

    • Capture the Safari window, an element, the full page, or the screen

    • Type: observe tool

    • Optional inputs:

      • display (number): Display index for screen mode, 1-based, defaults to the main display

      • mode (string: element, page, screen, window, default: window): Capture mode

      • selector (string): CSS selector for element mode

      • settle (number): For page mode, milliseconds to wait after each scroll for content to settle (default: 500). Raise for slow dynamic sites, lower for static sites.

      • share (boolean, default: false): Save to disk and return only the file path instead of the inline image

    • Returns: Inline base64 image when share is false, or { path, width, height, mimeType, ... } when share is true. Browser metadata { innerHeight, scrollHeight, pages } is included for non-screen modes.

  11. scroll

    • Scroll by direction or to a viewport-page index

    • Type: observe tool

    • Optional inputs:

      • direction (string: up or down)

      • page (number): Viewport-page index to scroll to

      • pixels (number): Pixels to scroll, paired with direction

  12. search

    • Search using the browser's default engine

    • Type: act tool

    • Required inputs:

      • text (string): Search query

  13. select

    • Choose an option in a <select> element

    • Type: act tool

    • Required inputs:

      • selector (string): CSS selector for the <select>

    • Optional inputs (one is required):

      • text (string): Option visible text

      • value (string): Option value attribute

  14. status

    • Return current Safari tabs and full tool surface

    • Type: observe tool

    • Returns: { tabs, tools }

  15. type

    • Type text into an input field

    • Type: act tool

    • Required inputs:

      • text (string): Text to type

    • Optional inputs:

      • append (boolean, default: false): Append instead of replace

      • selector (string): CSS selector for the input

      • submit (boolean, default: false): Press Enter after typing

  16. wait

    • Wait for selector or page text condition

    • Type: observe tool

    • Optional inputs (exactly one of the first three required):

      • selector (string): CSS selector to wait for

      • selectorGone (string): CSS selector to wait absent

      • text (string): Page text to wait for

      • timeoutMs (number): Timeout in milliseconds

    • Returns: { matched, elapsedMs }

  17. window

    • Manage browser window tabs

    • Type: observe tool

    • Required inputs:

      • action (string: close, list, open, switch)

    • Optional inputs:

      • index (number): Tab index for close and switch

      • url (string): URL for open

Available Tools

17 tools
clickC
Destructive

Click an element on the browser window

ParametersJSON Schema
NameRequiredDescriptionDefault
keyNoKey to press (e.g., Escape, ArrowRight, ArrowLeft, Enter, Tab)
selectorNoCSS selector to click when no text provided or to scope the text search
textNoText to match - visible text, image alt text, or aria-label
waitNoCSS selector to wait for after click
xNoX coordinate (pixels from left of viewport) to click at
yNoY coordinate (pixels from top of viewport) to click at

TDQS

C2.9/5.0
Behavior2/5

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

Annotations already indicate destructive nature, non-idempotence, and open world interaction. The description adds no further behavioral context, such as whether clicks trigger navigation, require DOM readiness, or any 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.

Conciseness4/5

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

The description is extremely concise (one phrase) with no wasted words. However, it sacrifices necessary detail for brevity.

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

Completeness2/5

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

With 6 parameters and no output schema, the description omits critical context about different click modes (selector, text, coordinates, key), the 'wait' parameter, and expected outcomes. It is insufficient for correct invocation.

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

Parameters3/5

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

The schema covers all 6 parameters with descriptions, so baseline is 3. The description does not add meaning beyond the schema; it merely restates the action.

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 clearly states the tool performs a click action on the browser window, distinguishing it from siblings like hover or type. However, it fails to mention that the tool can also press keys via the 'key' parameter, which is an unexpected secondary use.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like hover, select, or type. The description does not specify scenarios, prerequisites, or when not to use it.

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

closeA
DestructiveIdempotent

Close the working tab

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
closedYesTrue after the working tab is closed or no tab existed

TDQS

A3.9/5.0
Behavior3/5

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds no additional behavioral context beyond stating the action, so it meets the baseline but does not exceed it.

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

Conciseness5/5

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

The description is a single sentence with no fluff. It is front-loaded and every word is essential.

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

Completeness5/5

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

For a parameterless tool with an output schema, the description is sufficient. It fully captures the tool's functionality.

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

Parameters4/5

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

No parameters exist, so the description does not need to explain them. The baseline score of 4 applies.

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

Purpose5/5

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

The description 'Close the working tab' clearly states the verb and resource, distinguishing it from sibling tools like 'navigate' or 'refresh'. No ambiguity.

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

Usage Guidelines2/5

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 (e.g., 'wait' or 'scroll'). The description only states what it does, not when it is appropriate.

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

executeA
Destructive

Execute JavaScript in the browser context

ParametersJSON Schema
NameRequiredDescriptionDefault
scriptYesJavaScript code to execute

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare destructiveHint: true, idempotentHint: false, and openWorldHint: true, indicating the tool can be destructive and have side effects. The description does not add further behavioral context beyond what's in annotations.

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

Conciseness5/5

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

The description is a single, short sentence that is concise and to the point, with no wasted words.

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

Completeness3/5

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

While the tool has a simple interface with one parameter and annotations, the description could benefit from additional context about the scope of execution (e.g., page context, potential risks) given the destructive hint. It is minimally adequate.

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

Parameters3/5

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

The only parameter 'script' is described as 'JavaScript code to execute' in the schema, which is clear. Schema coverage is 100%, so the description adds no additional meaning beyond the schema.

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

Purpose5/5

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

The description 'Execute JavaScript in the browser context' clearly specifies the verb 'execute' and the resource 'JavaScript in the browser context', distinguishing it from sibling tools like 'click' or 'type' which are for specific UI actions.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives, nor any warnings about when not to use it. The description lacks any context about prerequisites or limitations.

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

hoverA
Idempotent

Hover over an element to reveal hover-triggered UI

ParametersJSON Schema
NameRequiredDescriptionDefault
selectorNoCSS selector for the target element
textNoVisible text to match (case-insensitive partial match)

TDQS

A4/5.0
Behavior4/5

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

Annotations already indicate idempotence and non-destructiveness. The description adds the behavioral context of revealing hover-triggered UI, which goes beyond annotations. However, it does not detail edge cases like missing elements or potential page changes.

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

Conciseness5/5

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

A single sentence that fully conveys the tool's purpose without any filler. Front-loaded and efficient.

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?

Given the tool's simplicity, no output schema, and rich sibling context, the description is adequately complete. It covers the core action, though it could mention that it performs a mouse hover event on the first matching element.

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

Parameters3/5

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

Schema coverage is 100% with both parameters described. The description adds no additional parameter information beyond what the schema provides, so baseline 3 is appropriate.

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

Purpose5/5

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

The description clearly states the action (hover) and the target (element) and hints at the purpose (reveal hover-triggered UI). It distinguishes from siblings like click or inspect.

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

Usage Guidelines3/5

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

The description implies usage for triggering hover effects, but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites.

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

inspectA
Read-onlyIdempotent

Inspect a page element by CSS selector

ParametersJSON Schema
NameRequiredDescriptionDefault
indexNoTab index in the front window; defaults to the current tab
selectorYesCSS selector for the target element

Output Schema

ParametersJSON Schema
NameRequiredDescription
foundYesWhether the selector matched any element
tagNoLowercase HTML tag name; present when found
textNoTrimmed visible text or aria-label or alt; present when found
visibleNoWhether the element is visible in the layout; present when found
disabledNoWhether the element is disabled or aria-disabled; present when found
attributesNoSelected key attributes on the element; present when found
rectNoViewport-relative bounding box; present when found

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint and idempotentHint, indicating a safe read operation. The description adds no further behavioral details (e.g., what happens to the page or element). It does not contradict annotations.

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

Conciseness5/5

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

The description is a single sentence with no wasted words. It is efficient and front-loaded with the key action and resource.

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

Completeness3/5

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

Given the existence of an output schema and annotations, the description is minimally adequate but lacks explanation of what 'inspect' returns (e.g., element properties). It does not cover usage context.

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

Parameters3/5

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

Schema description coverage is 100%, so the parameters are already well-documented. The description adds no extra meaning beyond stating 'by CSS selector', which matches the required 'selector' parameter.

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

Purpose5/5

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

The description clearly states the verb 'inspect', resource 'page element', and method 'by CSS selector'. It is specific and distinguishes from sibling tools like 'click' or 'hover'.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives like 'read' or 'hover'. It does not mention prerequisites or context.

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

openA

Open a blank tab as the working target

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
openedYesTrue after the working tab is created

TDQS

A4/5.0
Behavior3/5

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

Annotations already indicate destructiveHint=false, so the tool is safe. The description adds minimal behavior beyond that, not stating whether the tab becomes active or if previous tabs are affected. With annotations present, a 3 is reasonable as it provides no additional behavioral context.

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

Conciseness5/5

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

Single sentence, no wasted words. It is front-loaded and immediately clear.

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?

Given zero parameters and an output schema, the description is sufficient. It could mention whether the new tab becomes the active target, but the current text is adequate for a simple tool.

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

Parameters4/5

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

No parameters exist, and schema coverage is 100%. The description does not need to add parameter detail; baseline 4 applies as it does not mislead.

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

Purpose5/5

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

The description clearly states 'Open a blank tab as the working target', specifying the verb (Open), resource (blank tab), and intended effect (working target). This distinctively separates it from siblings like 'navigate' (which opens a URL) or 'click'.

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

Usage Guidelines3/5

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

No explicit guidance on when to use this tool versus alternatives like 'navigate' or 'window'. The context of sibling tools implies it's for new tabs, but the description lacks when-not-to-use advice.

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

readA
Read-onlyIdempotent

Get the page title, URL, and either text content or anchor links

ParametersJSON Schema
NameRequiredDescriptionDefault
indexNoTab index in the front window; defaults to the current tab
modeNoExtraction mode: full text content or anchor linkstext
selectorNoCSS selector to scope extraction

Output Schema

ParametersJSON Schema
NameRequiredDescription
titleYesPage title
urlYesPage URL
textNoExtracted text content; present when mode is "text"
linksNoAnchor links; present when mode is "links"
pagesYesNumber of viewport-sized pages
errorsNoConsole errors captured during the page session, when any
warningsNoConsole warnings captured during the page session, when any

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint. Description adds context on what data is extracted (title, URL, text/links), which is valuable 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.

Conciseness5/5

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

Single sentence, front-loaded with verb, no waste. Efficient and clear.

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

Completeness5/5

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

Tool is simple; description covers purpose. Output schema exists, so return values are documented elsewhere. No gaps evident.

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

Parameters3/5

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

Schema coverage is 100% with descriptions for all parameters. Description summarizes mode effect but adds no new meaning beyond schema.

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

Purpose5/5

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

Description states specific verb 'Get' and resources 'page title, URL, and either text content or anchor links', clearly distinguishing from sibling tools like click or navigate.

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?

Description implies use for extracting page content, but lacks explicit when-not or alternatives. However, the tool's purpose is clear enough to differentiate from siblings.

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

refreshB
Idempotent

Refresh the current browser page

ParametersJSON Schema
NameRequiredDescriptionDefault
hardNoBypass browser cache with hard refresh
selectorNoCSS selector to wait for after reload

Output Schema

ParametersJSON Schema
NameRequiredDescription
titleYesPage title after refresh
urlYesPage URL after refresh
innerHeightYesViewport height in pixels
scrollHeightYesTotal scrollable content height in pixels
scrollOffsetYesCurrent scroll offset from the top in pixels
pagesYesNumber of viewport-sized pages
tabsYesTotal tab count
selectorFoundNoWhether the selector was found, when provided

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already indicate destructiveHint=false, idempotentHint=true, and openWorldHint=true, so the description adds no extra behavioral context. It does not mention potential side effects like losing unsaved form data or triggering re-execution of scripts, which would be useful.

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?

The description is a single, direct sentence. It is front-loaded and contains no superfluous information. However, it could be slightly expanded to include context about parameters without losing conciseness.

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

Completeness3/5

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

For a simple action with two optional parameters and an output schema, the description is minimally adequate. It does not explain what happens after refresh (e.g., returns page content or success status), but the output schema may cover that. Lacks integration with sibling tools.

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

Parameters3/5

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

Schema coverage is 100%, and the description adds no additional meaning beyond the schema's own descriptions for 'hard' and 'selector'. The tool description merely repeats the action without clarifying parameter choices.

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

Purpose5/5

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

The description clearly states the verb 'Refresh' and the resource 'the current browser page', making the action unambiguous. It distinguishes itself from sibling tools like 'navigate' (which goes to a new URL) and 'open' (which opens a new page).

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like 'navigate' or 'reload' (if such existed). It does not specify prerequisites or conditions under which a refresh is appropriate (e.g., after form submission or state changes).

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

screenshotA
Read-onlyIdempotent

Capture a screenshot of the browser window, an element, the full page, or the screen

ParametersJSON Schema
NameRequiredDescriptionDefault
displayNoDisplay index for screen mode (1-based; defaults to the main display)
modeNoCapture modewindow
selectorNoCSS selector for element mode
settleNoPage mode: ms to wait after each scroll for content to settle (default 500)
shareNoSave to disk and return path instead of inline image

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare the tool as read-only and idempotent, so the safety profile is clear. The description adds the capture modes but does not disclose potential side effects (none expected) or other behavioral traits like file size limits or performance impact.

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

Conciseness5/5

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

Single sentence with no wasted words. The verb 'Capture' is front-loaded, and the rest specifies the target areas concisely.

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

Completeness3/5

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

Given 5 optional parameters and no output schema, the description provides basic coverage but misses details like the return format (base64 or file path based on share parameter). It is adequate but not thorough.

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

Parameters3/5

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

Input schema has 100% parameter descriptions, so the description adds no extra semantic value beyond listing mode options. Baseline score of 3 is appropriate since the schema does the heavy lifting.

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

Purpose5/5

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

The description clearly states the tool captures screenshots of various areas (window, element, page, screen), which directly matches the input schema's mode enum. It is distinct from sibling tools like click or navigate, which have entirely different purposes.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus other tools. The description does not mention prerequisites, scenarios where alternative tools might be better, or when not to use it.

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

scrollA

Scroll to specific viewport page or by direction with pixel amount

ParametersJSON Schema
NameRequiredDescriptionDefault
directionNoScroll direction
pageNoScroll to a specific viewport-sized page number
pixelsNoNumber of pixels to scroll

Output Schema

ParametersJSON Schema
NameRequiredDescription
innerHeightYesViewport height in pixels
scrollHeightYesTotal scrollable content height in pixels
scrollOffsetYesCurrent scroll offset from the top in pixels
pagesYesNumber of viewport-sized pages

TDQS

A3.5/5.0
Behavior3/5

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

Annotations already declare destructiveHint false and idempotentHint false. The description adds minimal behavioral context beyond stating the two scrolling modes (page and pixel). With annotations carrying some burden, the description is adequate but not richly informative.

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

Conciseness5/5

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

The description is a single sentence with 13 words, front-loading the core action and options. There is no wasted text; every word contributes to understanding.

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

Completeness3/5

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

Given the existence of an output schema, the description does not need to explain return values. However, it does not specify which element is scrolled (main viewport vs. a specific container), which is a notable omission for a scrolling tool.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema itself documents all three parameters. The description merely reiterates the two scrolling methods, adding no new meaning beyond what is already in the schema.

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

Purpose5/5

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

The description clearly states the tool scrolls to a specific viewport page or by direction with pixel amount. It uses specific verbs and resources, and it distinguishes scroll from sibling tools like navigate, which deals with URLs, and click/hover, which are element interactions.

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

Usage Guidelines2/5

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

The description lacks explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it or provide context for choosing scroll over other methods like execute for programmatic scrolling.

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

selectA
Destructive

Choose an option in a element

ParametersJSON Schema
NameRequiredDescriptionDefault
selectorYesCSS selector for the target <select> element
textNoOption visible text (case-insensitive partial match)
valueNoOption value attribute (takes precedence over text)

TDQS

A3.5/5.0
Behavior3/5

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

The description is consistent with the 'destructiveHint' annotation (mutation) but adds no additional behavioral details beyond what the annotation already conveys.

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

Conciseness5/5

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

Single short sentence that is front-loaded and efficient, with no wasted words.

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

Completeness3/5

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

Lacks mention of side effects or state changes (e.g., triggering events), but for a simple selection tool it is minimally adequate.

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

Parameters3/5

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

Schema coverage is 100%, with each parameter having a clear description. The tool description adds no extra semantics beyond the schema.

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

Purpose5/5

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

The description clearly states the action ('choose') and the target resource ('<select> element'), distinguishing it from sibling tools like 'click' or 'type'.

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

Usage Guidelines2/5

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 'click' or 'type', nor any mention of prerequisites or restrictions.

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

statusA
Read-onlyIdempotent

Get the current Safari tabs and the full tool surface with usage guidance

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
tabsYesTabs in the front Safari window, or empty when no window is open
toolsYesAll available tools with their schemas and usage guidance

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already mark the tool as read-only and idempotent; the description adds specific outputs (tabs and usage guidance), providing full behavioral clarity 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.

Conciseness5/5

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

A single, well-structured sentence conveys all necessary information without redundancy.

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

Completeness5/5

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

Given no parameters and availability of an output schema, the description fully covers what the tool does and what it returns.

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

Parameters4/5

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

The tool has no parameters, so the description does not need to explain them. With zero parameters, baseline score is 4.

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

Purpose5/5

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

The description clearly states the tool returns 'current Safari tabs' and 'full tool surface with usage guidance', distinguishing it from action-oriented sibling tools like click or navigate.

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?

The description implies this is for querying state rather than performing actions, but does not explicitly state when to use it or provide alternatives.

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

typeB
Destructive

Type text into a page input field

ParametersJSON Schema
NameRequiredDescriptionDefault
appendNoAppend to existing value instead of replacing
selectorNoCSS selector for the target input
submitNoSubmit form by pressing Enter after typing
textYesText to type

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already indicate destructiveHint=true and idempotentHint=false, so the description's statement about typing aligns. However, it does not add context beyond annotations; for example, it doesn't mention that submit=true may cause navigation or that append behavior differs.

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?

The description is a single concise sentence (7 words) that is easily parsable. It is front-loaded with the key action. However, it is perhaps too terse and could include more detail without losing conciseness.

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

Completeness3/5

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

The description is minimal but the schema covers all parameters comprehensively. Given the complexity (4 params, no output schema) and sibling tools, the description does not fully contextualize when this tool is appropriate, limiting completeness.

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

Parameters3/5

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

The input schema has 100% description coverage for all parameters (text, selector, append, submit). The description adds no additional meaning beyond what the schema already provides, 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.

Purpose5/5

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

The description clearly states 'Type text into a page input field', which is a specific verb+resource combination. It effectively distinguishes this tool from siblings like click, hover, or select, all of which perform different actions on the page.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention when to prefer type over select or paste, nor does it indicate any prerequisites or context (e.g., that the input must be focused or visible).

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

waitA
Read-onlyIdempotent

Wait for a selector to appear, disappear, or text to appear

ParametersJSON Schema
NameRequiredDescriptionDefault
selectorNoCSS selector to wait for
selectorGoneNoCSS selector to wait for absence of
textNoPage text to wait for (substring match in body innerText)
timeoutMsNoTimeout in milliseconds; defaults to the configured page-load timeout

Output Schema

ParametersJSON Schema
NameRequiredDescription
matchedYesWhether the condition was met before timeout
elapsedMsYesHow long the wait took, in milliseconds

TDQS

A4/5.0
Behavior4/5

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

Annotations already mark the tool as read-only and idempotent. The description adds behavioral context by specifying wait conditions (appearance, disappearance, text). It does not contradict annotations and provides moderate additional insight, though it omits details like polling behavior or timeout defaults.

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

Conciseness5/5

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

The description is a single sentence with no extraneous information. It packs the core functionality efficiently, making it easy to parse.

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?

Given the tool's simplicity, the description covers the main wait conditions. An output schema exists (though not shown), so return value explanation is not needed. However, the timeoutMs parameter behavior is not mentioned, leaving a minor gap.

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

Parameters3/5

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

The input schema already provides full descriptions for all four parameters (100% coverage). The description adds value by linking parameters to their behavioral roles (e.g., 'selector' for appearance), but this is incremental beyond schema descriptions. Baseline 3 is appropriate.

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

Purpose5/5

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

The description clearly states the action ('Wait') and the conditions (appear, disappear, text appear) with specific resources (selector, text). It distinguishes the tool from sibling tools that perform other actions like clicking or navigating.

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

Usage Guidelines3/5

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

The description implies usage for waiting on elements or text but provides no explicit guidance on when to use this tool versus alternatives, nor when not to use it. No exclusion criteria or alternative tool references are given.

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

windowC
Destructive

Manage browser window tabs

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYesTab action to perform
indexNoTab index for close and switch actions
urlNoURL to open in a new tab (open action only)

Output Schema

ParametersJSON Schema
NameRequiredDescription
tabsYesArray of tab info after the action

TDQS

C2.6/5.0
Behavior2/5

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

Annotations indicate destructiveHint=true, but the description adds no behavioral context (e.g., what happens when closing a tab, whether actions are reversible, or permission requirements). Since annotations already carry the safety signal, the description provides no extra value, scoring below the baseline.

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?

The description is extremely concise, consisting of a single phrase. While it wastes no words, it is so minimal that it sacrifices informativeness. It could be expanded slightly without losing conciseness, but for its length it is appropriately sized.

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

Completeness2/5

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

Despite having an output schema, the description does not reference return values. The tool supports multiple actions with different parameter requirements, but the description offers no complete picture of when each action is appropriate. It is too sparse to be fully useful.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema; it merely repeats the concept of tab management. No extra context for parameters like index or url is provided.

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

Purpose3/5

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

The description 'Manage browser window tabs' is overly generic. It implies tab operations but does not specify which actions (close, list, open, switch) are supported, which are defined in the input schema. This weakens clarity and differentiation from sibling tools like 'open' and 'close' which might refer to other contexts.

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

Usage Guidelines2/5

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

No usage guidelines are provided. The description does not advise when to use this tool over alternatives like 'open' (which might open a URL in the current tab) or 'close' (which might close a dialog). There is no explicit when-to-use or 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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 17 tool updatesv1.1.2
    • First observedclick
    • First observedclose
    • First observedexecute
    • First observedhover
    • First observedinspect
    • First observednavigate
    • First observedopen
    • First observedread
    • First observedrefresh
    • First observedscreenshot
    • First observedscroll
    • First observedsearch
    • First observedselect
    • First observedstatus
    • First observedtype
    • First observedwait
    • First observedwindow
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 17 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: click, hover, select, type, scroll are all different interactions; navigate, open, close, refresh, window manage tabs/navigation; read, inspect, screenshot extract data; execute runs JS; wait adds synchronization. No overlapping tools.

Naming Consistency5/5

All tool names are single lowercase words, predominantly verbs (click, navigate, type) with 'screenshot' as a slight exception but still consistent in style. No mixing of conventions.

Tool Count4/5

17 tools is slightly above the ideal range of 3-15, but the set covers a wide range of browser actions without feeling bloated. Each tool serves a distinct need in web automation.

Completeness4/5

The tool set covers navigation, element interaction, information retrieval, execution, and basic synchronization. Missing advanced features like file upload or alert handling, but core workflows for browsing and testing are well-supported.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers