Skip to main content
Glama
MarwanDevSpace

mcp-garry-codes

by MarwanDevSpace
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Analyze GLua Hot-Path Performance

analyze_performance
Read-onlyIdempotent

Profiles Garry's Mod Lua code statically to identify performance bottlenecks, GC issues, and per-frame hook allocations, preventing FPS stutter and tickrate drops.

Instructions

Profile Garry's Mod Lua code via static AST inspection to detect runtime performance traps, Zero-GC violations, and LuaJIT garbage collector bottlenecks. Purely analytical static inspection; does NOT execute code, does NOT evaluate scripts in a VM, and does NOT modify files on disk. Operates under zero-side-effect guarantees. Provide either file_path (workspace path) or code_content (raw snippet); when both are supplied, file_path takes precedence. Automatically inspects high-frequency rendering and simulation hooks (HUDPaint, RenderScreenspaceEffects, Think, Move). Use this tool to prevent client FPS stutter and server tickrate drops by flagging table allocations (Color(), Vector(), Angle()), unlocalized global lookups, and dynamic font creation inside per-frame hooks. Do NOT use for syntax or realm correctness checks (use lint_glua instead), network message exploit detection (use audit_net_security instead), or functional assertion testing (use run_glua_test instead). Returns a GModToolResult envelope with status ('success' or 'failed'), summary, and data containing performance_score (0-100), issues array (hook_name, line, severity, category, description, recommended_code), and allocation metrics (allocations_in_hot_path, global_calls_in_hot_path, dynamic_draw_calls).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
file_pathNoWorkspace path to .lua file to profile. Takes precedence over code_content when both are supplied.
code_contentNoDirect GLua source code snippet to profile. Ignored if file_path is provided.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
dataYesDomain-specific typed payload returned by the tool.
statusYesExecution status of the tool call ('success', 'partial', 'blocked', or 'failed').
summaryYesConcise, human-readable summary of operational findings, diagnostics, or execution outcome.
evidenceYesTraceability evidence including cited documentation and generated artifacts.
warningsYesList of non-fatal warnings, lint advisories, engine caveats, or security notices.
nextActionsNoActionable, ordered recommendations for the agent's immediate next steps.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / code_content / description
      Previous value: -"Direct Lua code snippet"New value: +"Direct GLua source code snippet to profile. Ignored if file_path is provided."
    • changedInput schema / properties / file_path / description
      Previous value: -"Workspace path to .lua file"New value: +"Workspace path to .lua file to profile. Takes precedence over code_content when both are supplied."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "data": {
+      "description": "Domain-specific typed payload returned by the tool.",
+      "properties": {
+        "issues": {
+          "description": "Detected hot-path performance bottlenecks and memory allocation traps.",
+          "items": {
+            "properties": {
+              "category": {
+                "description": "Category of performance defect.",
+                "enum": [
+                  "allocation_in_render_hook",
+                  "uncached_material",
+                  "uncached_font",
+                  "unlocalized_globals",
+                  "expensive_entity_iteration"
+                ],
+                "type": "string"
+              },
+              "description": {
+                "description": "Explanation of why this causes GC pressure or FPS drops.",
+                "type": "string"
+              },
+              "hook_name": {
+                "description": "Hook where issue occurred (e.g. 'HUDPaint', 'Think', 'RenderScreenspaceEffects').",
+                "type": "string"
+              },
+              "line": {
+                "description": "1-based line number.",
+                "type": "integer"
+              },
+              "recommended_code": {
+                "description": "Optimized replacement code pattern with pre-allocated tables.",
+                "type": "string"
+              },
+              "severity": {
+                "description": "Severity of performance impact.",
+                "enum": [
+                  "critical",
+                  "high",
+                  "medium"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "hook_name",
+              "line",
+              "severity",
+              "category",
+              "description",
+              "recommended_code"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "metrics": {
+          "description": "Detailed profiling metrics for the analyzed snippet.",
+          "properties": {
+            "allocations_in_hot_path": {
+              "description": "Number of Color/Vector/Angle allocations inside per-frame hooks.",
+              "type": "integer"
+            },
+            "dynamic_draw_calls": {
+              "description": "Dynamic font or material creation calls in hot paths.",
+              "type": "integer"
+            },
+            "global_calls_in_hot_path": {
+              "description": "Unlocalized global calls inside per-frame hooks.",
+              "type": "integer"
+            }
+          },
+          "required": [
+            "allocations_in_hot_path",
+            "global_calls_in_hot_path",
+            "dynamic_draw_calls"
+          ],
+          "type": "object"
+        },
+        "performance_score": {
+          "description": "Performance score out of 100 based on GC and call penalties.",
+          "maximum": 100,
+          "minimum": 0,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "performance_score",
+        "issues",
+        "metrics"
+      ],
+      "type": "object"
+    },
+    "evidence": {
+      "description": "Traceability evidence including cited documentation and generated artifacts.",
+      "properties": {
+        "artifacts": {
+          "description": "Files, packages, or manifests generated on disk or in memory.",
+          "items": {
+            "properties": {
+              "label": {
+                "description": "Descriptive label of the generated artifact.",
+                "type": "string"
+              },
+              "sha256": {
+                "description": "SHA-256 hash of the generated file.",
+                "type": "string"
+              },
+              "uri": {
+                "description": "File path or URI of the generated artifact.",
+                "type": "string"
+              }
+            },
+            "required": [
+              "label",
+              "uri"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "inputsDigest": {
+          "description": "SHA-256 digest of normalized tool inputs for auditability.",
+          "type": "string"
+        },
+        "sources": {
+          "description": "Cited documentation, wiki pages, or external web sources supporting the result.",
+          "items": {
+            "properties": {
+              "label": {
+                "description": "Display name or title of the cited resource.",
+                "type": "string"
+              },
+              "retrievedAt": {
+                "description": "ISO-8601 timestamp of source retrieval.",
+                "type": "string"
+              },
+              "uri": {
+                "description": "Canonical URI or URL of the documentation or source.",
+                "type": "string"
+              }
+            },
+            "required": [
+              "label"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "sources",
+        "artifacts"
+      ],
+      "type": "object"
+    },
+    "nextActions": {
+      "description": "Actionable, ordered recommendations for the agent's immediate next steps.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "status": {
+      "description": "Execution status of the tool call ('success', 'partial', 'blocked', or 'failed').",
+      "enum": [
+        "success",
+        "partial",
+        "blocked",
+        "failed"
+      ],
+      "type": "string"
+    },
+    "summary": {
+      "description": "Concise, human-readable summary of operational findings, diagnostics, or execution outcome.",
+      "type": "string"
+    },
+    "warnings": {
+      "description": "List of non-fatal warnings, lint advisories, engine caveats, or security notices.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "status",
+    "summary",
+    "data",
+    "warnings",
+    "evidence"
+  ],
+  "type": "object"
+}
  2. First observedv1.0.0

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that it is purely static analytic, does not execute code, does not evaluate in a VM, does not modify files, and operates under zero-side-effect guarantees—richer than the annotation hints alone. It also discloses automatic inspection of specific hooks. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is thorough (~200 words) and well-structured, front-loading the core purpose, then exclusions, usage guidance, and output format. Every sentence adds value, but it is slightly verbose and could be tightened without losing clarity. A 4 reflects good but not perfect conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two optional parameters and a defined return envelope, the description fully covers input precedence, behavioral guarantees, exclusions and alternatives, and the exact output structure (status, summary, performance_score, issues array fields, allocation metrics). No required information is missing for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both file_path and code_content fully explained in the schema. The description restates the precedence rule ('file_path takes precedence') but adds no new semantic details beyond what the schema already provides. Per the baseline rule for high coverage, a 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific function: profiling GLua via static AST inspection to detect performance traps, Zero-GC violations, and LuaJIT GC bottlenecks. It explicitly differentiates from sibling tools by naming lint_glua, audit_net_security, and run_glua_test as alternatives for other checks, making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states clearly when to use: to prevent client FPS stutter and server tickrate drops by flagging allocations, unlocalized lookups, and dynamic font creation in hooks. It also explicitly lists what not to use for (syntax/realm checks, network security, functional tests) and points to the precise alternative tools. This is unambiguous routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools