# [name] One-paragraph description of what this tool does and when an agent would call it. ## Behavior Long-form: what side effects it has, whether it's idempotent, whether it commits to disk, what state it mutates, what it returns. ## Args - `arg1: string` — description, valid range/format, required vs optional. ## Returns `ZmToolResult` — `{ exitCode, data?, stdout?, message? }`. `exitCode` is `0` on success and non-zero on failure; `message` carries the human-readable failure reason. ## Examples ```luau tools.call("[toolboxName].[name]", { arg1 = "foo" }) ```

# [name] One-paragraph description of what this tool does and when an agent would call it. ## Behavior Long-form: what side effects it has, whether it's idempotent, whether it commits to disk, what state it mutates, what it returns. ## Args - `arg1: string` — description, valid range/format, required vs optional. ## Returns `ZmToolResult` — `{ exitCode, data?, stdout?, message? }`. `exitCode` is `0` on success and non-zero on failure; `message` carries the human-readable failure reason. ## Examples ```luau tools.call("[toolboxName].[name]", { arg1 = "foo" }) ```

# [name] One-paragraph description of what this tool does and when an agent would call it. ## Behavior Long-form: what side effects it has, whether it's idempotent, whether it commits to disk, what state it mutates, what it returns. ## Args - `arg1: string` — description, valid range/format, required vs optional. ## Returns `ZmToolResult` — `{ exitCode, data?, stdout?, message? }`. `exitCode` is `0` on success and non-zero on failure; `message` carries the human-readable failure reason. ## Examples ```luau tools.call("[toolboxName].[name]", { arg1 = "foo" }) ```

# [name] One-paragraph description of what this tool does and when an agent would call it. ## Behavior Long-form: what side effects it has, whether it's idempotent, whether it commits to disk, what state it mutates, what it returns. ## Args - `arg1: string` — description, valid range/format, required vs optional. ## Returns `ZmToolResult` — `{ exitCode, data?, stdout?, message? }`. `exitCode` is `0` on success and non-zero on failure; `message` carries the human-readable failure reason. ## Examples ```luau tools.call("[toolboxName].[name]", { arg1 = "foo" }) ```

# shared Cross-tool helpers for the [name] toolbox. Every tool inside the toolbox can pull these in with `require(".shared")`. Holds the small set of helpers that more than one tool needs — typically the `ok(value, formatted?)` / `fail(message, exitCode?)` constructors that produce the canonical `[name]ToolResult` shape, plus any toolbox-wide parsers, validators, or shared state. Per-tool implementation stays inside each `<x>.tool/init.luau`; this module is not a place to forward logic from. ## Exports - `M.ok(value: any?, formatted: string?) -> [name]ToolResult` — success envelope (`exitCode = 0`, `ok = true`). - `M.fail(message: string, exitCode: number?) -> [name]ToolResult` — failure envelope (`exitCode` defaults to 1, `ok = false`). Types: - `[name]ToolResult = { stdout: string, stderr: string, exitCode: number, ok: boolean, value: any? }` - `stdout` — human-readable formatted output; empty when the op produces no text. - `stderr` — error message on failure; empty on success. - `exitCode` — POSIX-style exit code: `0` success, `1` generic failure, `2` bad arguments. - `ok` — `true` iff `exitCode == 0`. - `value` — structured return from the underlying op; `nil` for void ops. ## Usage ```luau local shared = require(".shared") function M.someTool(args) if not args.id then return shared.fail("missing id", 2) end return shared.ok({ id = args.id }, "created " .. args.id) end ``` ## Notes - Pure constructors — no engine calls, no state. Safe to call from any context. - Tools that opt into this shape get a stable envelope every other tool in the toolbox can rely on. Tools that do something custom can return whatever shape they want — `[name]ToolResult` is opt-in. - Per-tool implementations still own their own `--!desc` / `--!arg` / `--!return` / `--!example` annotations even when their result is constructed through these helpers.

# [name] One-paragraph description of what this module provides and who consumes it. ## Exports - `M.exampleFn(arg) -> result` — what it does and when to call it. - `M.exampleValue: type` — what value it carries. ## Usage ```luau local M = require("@<youridentity>::modules.[name]") M.exampleFn("foo") ``` ## Notes - Anything callers need to know about THIS module: required runtime ordering, state ownership, side effects.

# [name] One-paragraph description of what this module provides and who consumes it. ## Exports - `M.exampleFn(arg) -> result` — what it does and when to call it. - `M.exampleValue: type` — what value it carries. ## Usage ```luau local M = require("@<youridentity>::modules.[name]") M.exampleFn("foo") ``` ## Notes - Anything callers need to know about THIS module: required runtime ordering, state ownership, side effects.

# [name] One-paragraph description of what this module provides and who consumes it. ## Exports - `M.exampleFn(arg) -> result` — what it does and when to call it. - `M.exampleValue: type` — what value it carries. ## Usage ```luau local M = require("@<youridentity>::modules.[name]") M.exampleFn("foo") ``` ## Notes - Anything callers need to know about THIS module: required runtime ordering, state ownership, side effects.