lookup_function

Instructions

Implementation Reference

• server.py:86-103 (registration)

  MCP tool registration via @mcp.tool() decorator. Delegates to lsl_lookup_function() in tools/lookup.py.

  @mcp.tool()
  def lookup_function(name: str) -> dict:
      """
      Look up an LSL function by name.
  
      Returns the full function record: signature, parameters, return type,
      delay, energy cost, caveats, examples, related functions, and any known
      AI-specific pitfalls associated with this function.
  
      Falls back to fuzzy matching if the exact name is not found, and returns
      a 'did_you_mean' list when no match exists at all — helping catch
      hallucinated function names.
  
      Args:
          name: Function name, e.g. "llListen" or "llReplaceSubString".
      """
      log.info("lookup_function(%r)", name)
      return lsl_lookup_function(name)

• tools/lookup.py:119-172 (handler)

  Core handler that queries the SQLite DB with exact match, prefix match, and substring fallback. Returns full function record or error with 'did_you_mean' suggestions.

  def lsl_lookup_function(name: str) -> dict:
      """
      Look up an LSL function by name.
  
      Tries an exact match first, then falls back to a case-insensitive prefix
      match, then a LIKE search. Returns the full function record including
      parameters, caveats, examples, related functions, and any known AI pitfalls
      associated with this function.
  
      If the name does not match any real LSL function, returns an error dict
      with a 'did_you_mean' list of close matches.
  
      Args:
          name: The function name to look up, e.g. "llListen" or "lllisten".
  
      Returns:
          dict with keys: name, signature, return_type, description, parameters,
          delay, energy_cost, mono_only, deprecated, caveats, examples, related,
          permissions_required, scope, known_ai_pitfalls.
          On failure: {"error": str, "did_you_mean": list[str]}
      """
      con = _connect()
  
      # 1. Exact match (case-insensitive)
      row = con.execute(
          "SELECT * FROM functions WHERE lower(name) = lower(?)", (name,)
      ).fetchone()
  
      # 2. Prefix match
      if not row:
          row = con.execute(
              "SELECT * FROM functions WHERE lower(name) LIKE lower(?)",
              (name.rstrip("%") + "%",),
          ).fetchone()
  
      # 3. Substring match
      if not row:
          row = con.execute(
              "SELECT * FROM functions WHERE lower(name) LIKE lower(?)",
              (f"%{name}%",),
          ).fetchone()
  
      if not row:
          # Suggest close matches via FTS
          suggestions = con.execute(
              "SELECT name FROM functions_fts WHERE name MATCH ? LIMIT 5",
              (name,),
          ).fetchall()
          return {
              "error": f"No LSL function found matching '{name}'.",
              "did_you_mean": [s["name"] for s in suggestions],
          }
  
      return _hydrate_function(con, row)

• tools/lookup.py:32-114 (helper)

  Helper that hydrates a full function record from the DB, fetching parameters, caveats, examples, related functions, permissions, scope entries, and known AI pitfalls.

  def _hydrate_function(con: sqlite3.Connection, row: sqlite3.Row) -> dict:
      """
      Given a functions row, fetch all child records and return a complete dict.
      """
      fid = row["id"]
  
      params = con.execute(
          """
          SELECT position, name, type, description
          FROM function_parameters
          WHERE function_id = ?
          ORDER BY position
          """,
          (fid,),
      ).fetchall()
  
      caveats = con.execute(
          "SELECT caveat FROM function_caveats WHERE function_id = ?", (fid,)
      ).fetchall()
  
      examples = con.execute(
          "SELECT example FROM function_examples WHERE function_id = ?", (fid,)
      ).fetchall()
  
      related = con.execute(
          "SELECT related_name FROM function_related WHERE function_id = ?", (fid,)
      ).fetchall()
  
      permissions = con.execute(
          "SELECT permission FROM function_permissions WHERE function_id = ?", (fid,)
      ).fetchall()
  
      scope = con.execute(
          "SELECT scope, allowed FROM function_scope WHERE function_id = ?", (fid,)
      ).fetchall()
  
      pitfalls = con.execute(
          """
          SELECT id, category, title, bad_example, good_example, notes, ai_source
          FROM pitfalls
          WHERE category = 'nonexistent_functions'
             OR (bad_example LIKE '%' || ? || '%')
          """,
          (row["name"],),
      ).fetchall()
  
      return {
          "name":          row["name"],
          "signature":     row["signature"],
          "return_type":   row["return_type"],
          "description":   row["description"],
          "delay":         row["delay"],
          "energy_cost":   row["energy_cost"],
          "mono_only":     bool(row["mono_only"]),
          "deprecated":    bool(row["deprecated"]),
          "since_version": row["since_version"],
          "parameters": [
              {
                  "position":    p["position"],
                  "name":        p["name"],
                  "type":        p["type"],
                  "description": p["description"],
              }
              for p in params
          ],
          "caveats":              [c["caveat"] for c in caveats],
          "examples":             [e["example"] for e in examples],
          "related":              [r["related_name"] for r in related],
          "permissions_required": [p["permission"] for p in permissions],
          "scope":                [{"scope": s["scope"], "allowed": bool(s["allowed"])} for s in scope],
          "known_ai_pitfalls": [
              {
                  "id":          p["id"],
                  "category":    p["category"],
                  "title":       p["title"],
                  "bad_example": p["bad_example"],
                  "good_example": p["good_example"],
                  "notes":       p["notes"],
                  "ai_source":   p["ai_source"],
              }
              for p in pitfalls
          ],
      }