# Common definitions
_common:
  tabId: &tabId
    type: string
    description: Target tab ID

  selectorAndXpath: &selectorAndXpath
    selector:
      type: string
      description: The CSS selector to find a target Element for the action (uses first matching element)
    xpath:
      type: string
      description: An XPath expression to find a target Element for the action (alternative to selector, uses first matching element)

  oneOfSelectorOrXpath: &oneOfSelectorOrXpath
    oneOf:
      - required: [selector]
      - required: [xpath]

tools:
  list_tabs:
    description: List all connected browser tabs

  navigate:
    description: Navigate browser tab to specified URL
    required: [tabId, url]
    properties:
      tabId: *tabId
      url:
        type: string
        format: url
        description: URL to navigate to
      timeout:
        type: number
        description: Navigation timeout in milliseconds
        default: 30000

  back:
    description: Navigate back in browser history
    required: [tabId]
    properties:
      tabId: *tabId

  forward:
    description: Navigate forward in browser history
    required: [tabId]
    properties:
      tabId: *tabId

  click:
    description: >-
      Click on a page element using CSS selector or XPath. Only the first 
      matching element will be clicked. Returns the unique selector of the 
      clicked element. Note: May experience delays if Kapture DevTools panel 
      is not the active tab.
    required: [tabId]
    properties:
      tabId: *tabId
      <<: *selectorAndXpath
    oneOf:
      - required: [selector]
      - required: [xpath]

  hover:
    description: >-
      Hover over a page element using CSS selector or XPath. Only the first 
      matching element will be hovered. Returns the unique selector of the 
      hovered element. Note: May experience delays if Kapture DevTools panel 
      is not the active tab.
    required: [tabId]
    <<: *oneOfSelectorOrXpath
    properties:
      tabId: *tabId
      <<: *selectorAndXpath

  fill:
    description: >-
      Fill an input field with a value using CSS selector or XPath. Only the 
      first matching element will be filled. Returns the unique selector of 
      the filled element.
    required: [tabId, value]
    <<: *oneOfSelectorOrXpath
    properties:
      tabId: *tabId
      <<: *selectorAndXpath
      value:
        type: string
        description: Value to fill in the input

  select:
    description: >-
      Select an option from an HTML <select> dropdown element using CSS 
      selector or XPath. Only the first matching select element will be used. 
      Returns the unique selector of the select element. Note: Only works with 
      native HTML select elements, not custom dropdowns.
    required: [tabId, value]
    <<: *oneOfSelectorOrXpath
    properties:
      tabId: *tabId
      <<: *selectorAndXpath
      value:
        type: string
        description: Value attribute of the option to select

  keypress:
    description: >-
      Send a keypress event to the current tab or a specific element. Uses 
      Chrome DevTools Protocol for proper key simulation including navigation 
      keys (Tab, PageDown, arrows) and function keys. When delay > 500ms, 
      automatically simulates holding the key down with repeated events.
    required: [tabId, key]
    properties:
      tabId: *tabId
      key:
        type: string
        description: >-
          The key combination to press. Can be a single key (e.g., "a", 
          "Enter", "Tab", "PageDown", "F5") or a combination with modifiers 
          (e.g., "Control+a", "Shift+Tab", "Alt+F4", "Meta+Shift+p"). 
          Special keys: Enter, Tab, Delete, Backspace, Escape, Space, 
          ArrowUp/Down/Left/Right, PageUp/Down, Home, End, Insert, F1-F12. 
          Modifiers: Control (or Ctrl), Shift, Alt, Meta (or Cmd on Mac)
      <<: *selectorAndXpath
      delay:
        type: number
        description: >-
          Delay in milliseconds between keydown and keyup events. Default: 
          50ms. Range: 0-60000ms. When > 500ms, simulates holding the key 
          down with auto-repeat
        default: 50
        minimum: 0
        maximum: 60000
      timeout:
        type: number
        description: >-
          Command timeout in milliseconds. Default: 5000ms. Automatically 
          extended for long delays
        minimum: 1000
        maximum: 70000

  screenshot:
    description: >-
      Capture a screenshot of the page or specific element using CSS selector 
      or XPath. When a selector/xpath is provided, only the first matching 
      element will be captured. Returns the unique selector of the captured 
      element if applicable.
    required: [tabId]
    properties:
      tabId: *tabId
      <<: *selectorAndXpath
      scale:
        type: number
        description: Scale factor (0.1-1.0) to reduce screenshot size (default 0.3)
        default: 0.3
        minimum: 0.1
        maximum: 1
      format:
        type: string
        description: Image format (default webp for best compression)
        default: webp
        enum: [webp, jpeg, png]
      quality:
        type: number
        description: Compression quality for webp/jpeg (0.1-1.0, default 0.85)
        default: 0.85
        minimum: 0.1
        maximum: 1

  evaluate:
    description: >-
      Execute JavaScript code in the browser context. Return values are 
      automatically serialized to JSON-safe format: functions become 
      "[Function: name]", DOM elements include unique CSS selectors, 
      NodeLists/HTMLCollections are converted to arrays with selectors, 
      circular references are handled, etc.
    required: [tabId, code]
    properties:
      tabId: *tabId
      code:
        type: string
        description: JavaScript code to execute. The last expression is returned as the result.

  dom:
    description: >-
      Get outerHTML of the body or a specific element using CSS selector or 
      XPath. When a selector/xpath is provided, only the first matching 
      element will be used. Returns the unique selector of the element if 
      applicable.
    required: [tabId]
    properties:
      tabId: *tabId
      <<: *selectorAndXpath

  elementsFromPoint:
    description: Get information about all elements at a specific coordinate in the viewport
    required: [tabId, x, y]
    properties:
      tabId: *tabId
      x:
        type: number
        description: X coordinate relative to the viewport
      y:
        type: number
        description: Y coordinate relative to the viewport

  querySelectorAll:
    description: >-
      Query all elements matching a CSS selector or XPath and get detailed 
      information about each element
    required: [tabId]
    <<: *oneOfSelectorOrXpath
    properties:
      tabId: *tabId
      <<: *selectorAndXpath