Skip to main content
Glama
gaforov

selenium-mcp

by gaforov
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

selector_hint_save

Saves a working element selector under a short key for a site, so later runs can reuse it instead of rediscovering the element.

Instructions

Remember a selector that worked, under a short key for a site, so later runs can reuse it instead of rediscovering the element. Hints are saved to a JSON file on disk (.selenium-mcp/selector-hints.json in the server's working directory, or SELENIUM_MCP_SELECTOR_HINTS_PATH) and survive restarts. Save a hint after a selector has worked, e.g. after a successful click. Returns the saved hint.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
keyYesShort name for the element, e.g. 'login_button' or 'search_box' (1-128 chars).
domainNoSite hostname, e.g. 'www.saucedemo.com'. Defaults to the hostname of the page currently open.
selectorYesHow to find the element, e.g. { by: 'css', value: '#login-button' } or { by: 'id', value: 'user-name' }. Prefer id, name, or a short CSS selector.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.3.0
    • addedInput schema / properties / domain / description
      Added value: +"Site hostname, e.g. 'www.saucedemo.com'. Defaults to the hostname of the page currently open."
    • addedInput schema / properties / key / description
      Added value: +"Short name for the element, e.g. 'login_button' or 'search_box' (1-128 chars)."
    • addedInput schema / properties / selector / description
      Added value: +"How to find the element, e.g. { by: 'css', value: '#login-button' } or { by: 'id', value: 'user-name' }. Prefer id, name, or a short CSS selector."
    • addedInput schema / properties / selector / properties / by / description
      Added value: +"Locator strategy: css, xpath, id, name, class/className, tag/tagName, linkText, or partialLinkText."
    • addedInput schema / properties / selector / properties / value / description
      Added value: +"The locator for that strategy, e.g. '#login-button' for css, 'user-name' for id, or //button[@type=\"submit\"] for xpath."
  2. Addedv0.2.0

TDQS

A4.3/5.0
Behavior5/5

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses persistence location (.selenium-mcp/selector-hints.json or SELENIUM_MCP_SELECTOR_HINTS_PATH), durability across restarts, and the return value. These are non-obvious side effects an agent needs.

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

Conciseness4/5

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

Front-loads what the tool does, then storage location, then the usage trigger, then return value. Slightly dense but every sentence adds information; no 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?

Covers purpose, persistence, keying, and return value for a 3-param nested-object tool with rich schema. No output schema exists, so explaining the return briefly is appropriate. Missing only explicit sibling/alternative routing, which is minor.

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%, so the schema fully documents key, domain, and selector (including enum strategies and the default-to-current-hostname behavior). The description adds no parameter-level detail beyond what the schema provides, so baseline 3 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?

States a specific verb (save/remember) and resource (selector hint keyed by site), and distinguishes itself from the sibling read tool selector_hint_get by clarifying the write direction. The keying and domain scoping is explicit.

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?

Gives a concrete when-to-use trigger ('Save a hint after a selector has worked, e.g. after a successful click'). Does not explicitly name selector_hint_get as the read counterpart or state when not to save, but the usage context is clear.

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

Deploy Server

Other Tools