list_events
Retrieve valid LSL event signatures. Call without arguments to list all events, or specify an event name to get its full signature and parameter details.
Instructions
Return valid LSL event signatures.
Call with no arguments to get all events and verify an event name exists. Call with a name to get the full signature and parameter details.
Args: name: Optional event name, e.g. "listen" or "touch_start". Omit to return all events.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No |
Implementation Reference
- tools/reference.py:62-123 (handler)The core handler function that queries the SQLite database for LSL events. If a name is given, it performs exact (case-insensitive) match, then substring fallback, returning a hydrated event record or an error with valid event names. If no name, returns a summary list of all events.
def lsl_list_events(name: str | None = None) -> dict: """ Return valid LSL event signatures. Events are the entry points of LSL scripts (state_entry, touch_start, listen, timer, etc.). AI tools sometimes invent event names that do not exist — use this tool to verify an event name before using it. Args: name: Optional event name to look up exactly, e.g. "listen" or "touch_start". Omit to return all events. Returns: If name provided: Single event record with keys: name, signature, description, since_version, parameters. On miss: {"error": str, "valid_events": list[str]} If name omitted: {"count": int, "events": list of {name, signature, description}} """ con = _connect() if name: # Exact match first, then case-insensitive row = con.execute( "SELECT * FROM events WHERE lower(name) = lower(?)", (name,) ).fetchone() if not row: # Substring fallback row = con.execute( "SELECT * FROM events WHERE lower(name) LIKE lower(?)", (f"%{name}%",), ).fetchone() if not row: all_names = con.execute( "SELECT name FROM events ORDER BY name" ).fetchall() return { "error": f"No LSL event found matching '{name}'.", "valid_events": [r["name"] for r in all_names], } return _hydrate_event(con, row) # Return all events — summary only (no parameters) rows = con.execute( "SELECT * FROM events ORDER BY name" ).fetchall() return { "count": len(rows), "events": [ { "name": r["name"], "signature": r["signature"], "description": r["description"], } for r in rows ], } - server.py:162-175 (registration)The MCP tool registration and entry point. The @mcp.tool() decorator on server.py registers 'list_events' as an MCP tool. It delegates to the handler lsl_list_events() from tools/reference.py.
@mcp.tool() def list_events(name: str | None = None) -> dict: """ Return valid LSL event signatures. Call with no arguments to get all events and verify an event name exists. Call with a name to get the full signature and parameter details. Args: name: Optional event name, e.g. "listen" or "touch_start". Omit to return all events. """ log.info("list_events(name=%r)", name) return lsl_list_events(name) - tools/reference.py:32-57 (helper)Helper that hydrates a full event record by fetching child parameters from the event_parameters table and assembling them into a structured dict.
def _hydrate_event(con: sqlite3.Connection, row: sqlite3.Row) -> dict: params = con.execute( """ SELECT position, name, type, description FROM event_parameters WHERE event_id = ? ORDER BY position """, (row["id"],), ).fetchall() return { "name": row["name"], "signature": row["signature"], "description": row["description"], "since_version": row["since_version"], "parameters": [ { "position": p["position"], "name": p["name"], "type": p["type"], "description": p["description"], } for p in params ], } - tests/conftest.py:85-271 (schema)Test fixture data defining the shape of event records (name, signature, description, since_version, parameters) — serves as the schema/type definition for event objects returned by list_events.
FIXTURE_EVENTS = [ { "name": "listen", "signature": "listen(integer channel, string name, key id, string message)", "description": "Triggered when a listened message is received.", "since_version": None, "parameters": [ {"position": 0, "name": "channel", "type": "integer", "description": "Channel"}, {"position": 1, "name": "name", "type": "string", "description": "Speaker name"}, {"position": 2, "name": "id", "type": "key", "description": "Speaker UUID"}, {"position": 3, "name": "message", "type": "string", "description": "Message content"}, ], }, { "name": "touch_start", "signature": "touch_start(integer num_detected)", "description": "Triggered when an avatar starts touching the object.", "since_version": None, "parameters": [ {"position": 0, "name": "num_detected", "type": "integer", "description": "Number of touching agents"}, ], }, { "name": "state_entry", "signature": "state_entry()", "description": "Triggered on entering a state.", "since_version": None, "parameters": [], }, ] FIXTURE_CONSTANTS = [ {"name": "NULL_KEY", "type": "key", "value": "00000000-0000-0000-0000-000000000000", "category": "string", "description": "A null/empty key value."}, {"name": "TRUE", "type": "integer", "value": "1", "category": "math", "description": "Boolean true."}, {"name": "FALSE", "type": "integer", "value": "0", "category": "math", "description": "Boolean false."}, {"name": "PUBLIC_CHANNEL", "type": "integer", "value": "0", "category": "channels", "description": "The public chat channel."}, {"name": "PERMISSION_TAKE_CONTROLS", "type": "integer", "value": "4", "category": "permissions", "description": "Permission to take controls."}, ] FIXTURE_PITFALLS = [ { "id": "lang_001", "category": "reserved_words", "title": "LSL type name used as variable name", "bad_example": "key key = llGetOwner();", "good_example": "key owner = llGetOwner();", "notes": "All primitive type names are reserved in LSL.", "ai_specific": 1, "portable_only": 1, "ai_source": "kiro", "created_at": "2026-01-01T00:00:00Z", }, { "id": "func_001", "category": "nonexistent_functions", "title": "llStringReplace does not exist in LSL", "bad_example": "llStringReplace(src, old, new)", "good_example": "llReplaceSubString(src, pattern, replacement, count)", "notes": "llStringReplace is a hallucination.", "ai_specific": 1, "portable_only": 1, "ai_source": "kiro", "created_at": "2026-01-01T00:00:00Z", }, { "id": "syn_001", "category": "unsupported_syntax", "title": "Ternary operator not supported in LSL", "bad_example": "integer x = (a > 0) ? 1 : 0;", "good_example": "integer x;\nif (a > 0) x = 1;\nelse x = 0;", "notes": "LSL has no ternary operator.", "ai_specific": 1, "portable_only": 1, "ai_source": "both", "created_at": "2026-01-01T00:00:00Z", }, { "id": "syn_002", "category": "unsupported_syntax", "title": "Switch statements not supported in LSL", "bad_example": "switch(channel) { case 1: break; }", "good_example": "Use if/else if chains.", "notes": "No switch in portable LSL.", "ai_specific": 1, "portable_only": 1, "ai_source": "both", "created_at": "2026-01-01T00:00:00Z", }, ] # ── DB builder ──────────────────────────────────────────────────────────────── def _build_test_db(con: sqlite3.Connection) -> None: schema = (ROOT / "db" / "schema.sql").read_text() con.executescript(schema) for f in FIXTURE_FUNCTIONS: con.execute( """ INSERT INTO functions (name, signature, return_type, description, energy_cost, delay, mono_only, deprecated, since_version) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) """, ( f["name"], f["signature"], f["return_type"], f["description"], f.get("energy"), f.get("delay"), int(f.get("mono_only", False)), int(f.get("deprecated", False)), f.get("since_version"), ), ) fid = con.execute( "SELECT id FROM functions WHERE name = ?", (f["name"],) ).fetchone()[0] for p in f.get("parameters", []): con.execute( "INSERT INTO function_parameters (function_id, position, name, type, description) VALUES (?,?,?,?,?)", (fid, p["position"], p["name"], p["type"], p.get("description")), ) for c in f.get("caveats", []): con.execute( "INSERT INTO function_caveats (function_id, caveat) VALUES (?,?)", (fid, c) ) for r in f.get("related", []): con.execute( "INSERT INTO function_related (function_id, related_name) VALUES (?,?)", (fid, r) ) for e in FIXTURE_EVENTS: con.execute( "INSERT INTO events (name, signature, description, since_version) VALUES (?,?,?,?)", (e["name"], e["signature"], e["description"], e.get("since_version")), ) eid = con.execute( "SELECT id FROM events WHERE name = ?", (e["name"],) ).fetchone()[0] for p in e.get("parameters", []): con.execute( "INSERT INTO event_parameters (event_id, position, name, type, description) VALUES (?,?,?,?,?)", (eid, p["position"], p["name"], p["type"], p.get("description")), ) for c in FIXTURE_CONSTANTS: con.execute( "INSERT INTO constants (name, type, value, category, description, deprecated) VALUES (?,?,?,?,?,?)", (c["name"], c["type"], c["value"], c.get("category"), c.get("description"), 0), ) for p in FIXTURE_PITFALLS: con.execute( """ INSERT INTO pitfalls (id, category, title, bad_example, good_example, notes, ai_specific, portable_only, ai_source, created_at) VALUES (?,?,?,?,?,?,?,?,?,?) """, ( p["id"], p["category"], p["title"], p["bad_example"], p["good_example"], p["notes"], p["ai_specific"], p["portable_only"], p["ai_source"], p["created_at"], ), ) con.commit() # ── Fixtures ────────────────────────────────────────────────────────────────── @pytest.fixture(scope="session") def test_db_path(tmp_path_factory) -> Path: """ Build a temporary SQLite database from schema + fixtures. Scoped to the session so it is created once and shared across all tests. """ db_path = tmp_path_factory.mktemp("db") / "lsl_test.db" con = sqlite3.connect(db_path) con.execute("PRAGMA foreign_keys=ON") _build_test_db(con) con.close() return db_path @pytest.fixture(autouse=True) def patch_db_path(test_db_path, monkeypatch): """