executeJs Reference

The JavaScript that runs in the visitor's browser when an AI agent calls your tool.

Execution context

Runs synchronously or asynchronously in the browser's JavaScript engine
Has full access to document, window, and all browser APIs
Runs with the same permissions as the page's own scripts
No Node.js APIs (require, fs, process are not available)

The `args` object

args contains the parameters passed by the AI agent, typed according to your input schema.

// Tool with inputSchema: { productId: string, quantity: number }
// args = { productId: "shoe-01", quantity: 2 }
const product = document.querySelector(`[data-id="${args.productId}"]`)

Return value

Return a plain object. The AI agent receives this as the tool's result.

// Success
return { success: true, cartCount: 3 }
 
// Failure (agent-visible, not an exception)
return { success: false, error: "Product not found" }

Throwing an exception also works — the agent receives { error: "message" }.

Async support

executeJs supports async/await:

const res = await fetch('/api/cart/add', {
  method: 'POST',
  body: JSON.stringify({ productId: args.productId })
})
return await res.json()

Examples

Click a button:

const btn = document.querySelector('#checkout-btn')
if (!btn) return { success: false, error: 'Button not found' }
btn.click()
return { success: true }

Fill and submit a form:

document.querySelector('#search-input').value = args.query
document.querySelector('#search-form').submit()
return { success: true, query: args.query }

Read data from the page:

const items = [...document.querySelectorAll('.product-card')].map(el => ({
  id: el.dataset.id,
  name: el.querySelector('.name')?.textContent?.trim(),
  price: el.querySelector('.price')?.textContent?.trim(),
}))
return { results: items, total: items.length }

Call an internal API:

const res = await fetch('/api/wishlist', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ productId: args.productId })
})
if (!res.ok) return { success: false, error: `API error ${res.status}` }
return await res.json()

Security linting

The editor warns about dangerous patterns in real time. Full rule list:

Pattern	Severity	Reason
`eval(`	Error	Executes arbitrary strings
`new Function(`	Error	Same risk as eval
`document.cookie`	Error	Exposes session tokens
`document.write(`	Error	Can overwrite the page
`input[type=password]`	Error	Password field scraping
`setTimeout/setInterval` with string	Error	String callbacks = eval
`__proto__` / `prototype[`	Error	Prototype pollution
`localStorage`	Warning	May contain sensitive data
`sessionStorage`	Warning	May contain sensitive data
`innerHTML =`	Warning	XSS risk with unsanitised args
`window.location =`	Warning	Redirect may confuse agent
`fetch(external URL)`	Warning	Possible data exfiltration
`XMLHttpRequest`	Warning	Prefer fetch
`navigator.geolocation`	Warning	Location access
`postMessage(`	Warning	Cross-origin messaging