API Reference

Every alethia_* tool, in one place.

Connect your agent to Alethia through MCP. Explore the tools for execution, inspection, policy checks, and run evidence, with parameter references and example requests.

Jump to a tool

MCP tool surface

15 tools for your agent workflow.

Example requests are prompts for your agent. Parameter tables describe the MCP calls it sends.

Agent prompts and runtime instructions are different. Ask your agent for a task in your own words. The agent sends structured MCP arguments. In the cockpit instruction window, write one supported instruction per line:

navigate to http://localhost:3000/login
click Sign In
assert the dashboard heading is visible

Run a task

alethia_tell

Ask for it: "Sign in and verify the dashboard loads." Supports conditional steps (if cookie banner exists, click Accept) and safety assertions (expect block: click Delete, to confirm EA1 blocks a destructive action rather than treating the refusal as a failure).

Sensitive fields are blocked unless the caller explicitly sets allowSensitiveInput: true. Use this only for authorized authentication or payment tests; a natural-language request alone does not set the flag.

Drives the browser with plain English and reports what changed, whether anything was blocked, and a tamper-evident record of the run.

Param	Type	Required	Description
`instructions`	string	yes	One or more plain-English test instructions, newline-separated.
`name`	string	no	Short label for the run, shown in cockpit history and audit trails. Strongly recommended.
`allowSensitiveInput`	boolean	no	Allows typing into password, token, credit card, and other sensitive fields. Only for legitimate auth/payment flow tests.

Result Per-step results, policy audit records, and an integrity hash.

Run parallel tasks

alethia_tell_parallel

Licensed Up to 2 concurrent specs without a valid license; up to 10 with one. These are technical concurrency limits; permitted use is governed by your license.

Ask for it: "Check the dashboard and the settings page at the same time."

Runs several test flows at once, each against its own page, and reports all results together.

Headless mode only. Each parallel spec runs in its own hidden window with no cockpit view — there's no way for a human to watch it live, so this tool refuses to run in an interactive cockpit session and only works under ALETHIA_HEADLESS=1 / CI.

Param	Type	Required	Description
`specs`	array	yes	A non-empty array. Each item requires a string `url` and string `instructions`; string `name` is optional.

Result Combined results for the supplied test specs.

Preview instructions

alethia_compile

Ask for it: "Show me what that test would do before you run it."

Previews a test — what it would do — without actually running anything against the page.

Param	Type	Required	Description
`instructions`	string	yes	Plain-English instructions to preview.

Result Compiled instructions, per-line confidence scores, and parsing warnings.

Serve demo pages

alethia_serve_demo

Ask for it: "Serve the demo pages so I can see them in the preview panel."

Starts a local server for Alethia's built-in demo pages so they're reachable at a real localhost URL instead of a file path.

No parameters.

Result A localhost base URL and a list of available demo pages.

Evaluate JavaScript

alethia_eval

Ask for it: "How many items are in that list right now?"

Answers questions plain-English steps can't — counting elements, reading computed styles, checking stored values.

Param	Type	Required	Description
`expression`	string	yes	JavaScript expression to evaluate in the page context.

Result The evaluated expression’s result from the target page.

Take a screenshot

alethia_screenshot

Ask for it: "Take a screenshot so I can see what that looks like."

Captures what the browser is currently showing.

No parameters.

Result A PNG screenshot returned as a base64-encoded image.

Check runtime status

alethia_status

Ask for it: "Is Alethia actually running? What version?"

A quick health check — confirms Alethia is reachable and reports its current state.

No parameters.

Result Runtime version, policy profile, kill-switch state, statistics, current domain, and capabilities.

Check safety policy

alethia_assert_safety

Ask for it: "Prove the safety gate actually blocks destructive actions on this page."

Discovers destructive controls on the target page and returns a per-action policy report. Review the discovered controls and results; this is not a guarantee that every possible destructive action is covered.

Param	Type	Required	Description
`url`	string	yes	The URL to navigate to and audit.

Result A per-action block/allow report for discovered destructive controls.

Stop automation

alethia_activate_kill_switch

Ask for it: "Stop everything right now — something looks wrong."

An emergency stop. Halts all automation immediately; only a human can clear it from the cockpit.

Param	Type	Required	Description
`reason`	string	no	Optional explanation that lands in the audit trail.

Result Activates the stop condition; later task calls are blocked until it is reset.

Check accessibility

alethia_audit_wcag

Licensed Requires a valid runtime license. Contact team@vitron.ai for current availability.

Ask for it: "Audit this page for accessibility."

Checks the current page for WCAG 2.1 AA accessibility findings using axe-core.

Automated findings do not establish WCAG conformance. Combine these checks with manual review and assistive-technology testing.

No parameters.

Result Accessibility findings with rule IDs, impact levels, and issue counts.

Check security controls

alethia_audit_nist

Licensed Requires a valid runtime license. Contact team@vitron.ai for current availability.

Ask for it: "Check this page for supported security-control findings."

Checks the page against 8 NIST SP 800-53 controls covering login/session handling, credential hygiene, and input validation. Some controls are checked against real behavior, not just markup.

Most NIST SP 800-53 controls are organizational or infrastructure controls that can't be assessed by inspecting a rendered page. Treat this as an early signal during development, not as compliance evidence for an audit or ATO package.

No parameters.

Result Security-control findings with control IDs and severity levels.

Export session evidence

alethia_export_session

Evaluation use Commercial or production use requires a written license.

Ask for it: "Export a signed evidence pack of everything you just did."

Exports recorded session tool calls with timestamps, inputs, outputs, policy decisions, and integrity information. Review the contents before sharing: exported records can contain application data.

No parameters.

Result Recorded session calls, timestamps, policy decisions, and integrity information.

Draft test scenarios

alethia_propose_tests

Ask for it: "Generate tests for this page — I haven't covered it yet."

Scans interactive elements on the target page and returns candidate test blocks, including safety checks for discovered destructive controls. Review the generated tests before execution.

Param	Type	Required	Description
`url`	string	yes	The URL to navigate to and scan.

Result Candidate plain-English test blocks for review before execution.

Show cockpit

alethia_show_cockpit

Ask for it: "Show me the cockpit — I want to watch this happen live."

Opens the live oversight window so you can watch the agent drive the page in real time.

No parameters.

Hide cockpit

alethia_hide_cockpit

Ask for it: "Hide the cockpit, just keep it running in the background."

Hides the oversight window. Everything keeps running underneath.

No parameters.