Skip to main content
Glama

format_scripts

DestructiveIdempotent

Formats Luau scripts on disk with StyLua over a synced script mirror, or reports unformatted files with check mode for use as a pre-commit gate. Scope runs to specific paths or the whole mirror.

Instructions

Format Luau on disk with StyLua (the standard Roblox formatter) over a place's synced script mirror. Default formats in place; check:true reports what's NOT formatted WITHOUT writing (a --check diff) — use it as a pre-commit gate so git diffs and snapshots stay clean. Respects a .stylua.toml in the project. Scope with paths (relative to the mirror root) or format the whole mirror. Needs StyLua installed (auto-detected or TUFAN_STYLUA_PATH).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "format_scripts"
  }
}

Input Schema

NameRequiredDescriptionDefault
checkNodon't write — just report unformatted files (default false)
pathsNofiles/dirs relative to the script-mirror root (default: the whole mirror)
placeNoTarget place (PlaceId or project name). Defaults to the bound/sole connected place.
timeoutSecondsNomax seconds for the run (default 120, max 600)

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.4/5.0
Behavior5/5

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

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true) by disclosing the external dependency and how it is located ('auto-detected or TUFAN_STYLUA_PATH'), that a `.stylua.toml` in the project is respected, and that `check:true` performs a non-writing diff. These are real prerequisites and side-effect details an agent could not derive from the structured fields.

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

Conciseness5/5

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

Four tightly packed sentences, front-loaded with the core action, then mode, config, scope, and prerequisite. No filler, and the check-mode caveat is placed immediately after the default behavior where it matters most.

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

Completeness4/5

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

For a four-parameter, no-output-schema tool, it covers purpose, side effects, config discovery, scope, and the prerequisite, which is nearly everything an agent needs to call it correctly. Minor gaps remain, such as whether formatting is backed up or how the `place` parameter behaves with multiple connected places, though the schema partially covers the latter.

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 coverage is 100%, so all four parameters are already documented, and the description largely restates them. It does add a little meaning, clarifying that `paths` are relative to the mirror root and that `check` produces a `--check` diff that writes nothing. That incremental value over the schema is modest, so the baseline of 3 holds.

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?

States a concrete verb and resource ('Format Luau on disk with StyLua') plus the exact target ('a place's synced script mirror'), which cleanly distinguishes it from sibling tools like lint_scripts or edit_script_lines. An agent knows immediately that this rewrites files on disk rather than editing script content directly.

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

Usage Guidelines4/5

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

Explicitly frames the two modes of use: default in-place formatting versus `check:true` as a pre-commit gate to keep git diffs and snapshots clean. Scoping guidance ('with `paths` or format the whole mirror') is also given. It stops short of naming sibling alternatives such as lint_scripts, so guidance is strong but not exhaustive.

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