Skip to main content
Glama

macro-execute

Destructive

Run a macro the way its hotbar button does: a chat macro posts its command, a script macro runs its JavaScript with GM rights (needs the module setting Allow Script Macros, off by default). args reaches a script macro as args / scope.args and the macro's return value comes back as result — bridge module 8.18.0+; older modules take no args and answer no result (the effect shows in chat-list or the world).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "macroId": "<macroId>"
    },
    "name": "macro-execute"
  }
}

Input Schema

NameRequiredDescriptionDefault
argsNoJSON object the macro reads as args (target, item, options); up to 64 KB
actorIdNoActor ID (from actor-list or actor-filter); the macro sees it as actor
macroIdYesMacro ID (from macro-list)
tokenIdNoToken ID on the active scene (from token-list); the macro sees it as token

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / args
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "JSON object the macro reads as args (target, item, options); up to 64 KB",
      +  "type": "object"
      +}
  2. Added

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations: it discloses that script macros run with GM rights, that a module setting gates this, that behavior differs by bridge module version (8.18.0+ vs older), and how args/result are plumbed. The destructiveHint annotation signals risk, but the description explains the actual privilege and compatibility consequences, which is substantial added value.

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?

Front-loaded with the core behavior and the two macro modes, then the compatibility caveat. Every clause carries information, though the single long sentence with nested parentheticals is dense and would parse more easily split in two.

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 destructive, 4-parameter execution tool with no output schema, the description covers the permission model, version compatibility, argument passing, and return-value behavior — including the older-module fallback where the effect is only visible as a side effect. Nothing essential to calling it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description adds genuine semantics by explaining that 'args' is surfaced to the script macro as args/scope.args and that the macro's return comes back as result. It does not clarify actorId/tokenId beyond what the schema already documents.

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 specific verb ('Run') and resource ('a macro') and immediately splits the behavior into the two macro kinds (chat posts a command, script runs JavaScript), which tells an agent exactly what will happen. This is clearly distinguishable from sibling macro-get/macro-list/macro-create, which read or mutate definitions rather than execute them.

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?

Provides a real gating condition: script macros need the 'Allow Script Macros' module setting, which is off by default, so the agent knows when the call will fail or be refused. It does not name alternatives (e.g., chat-send for a plain command) or state when not to invoke it, so it stops short of a 5.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources