Skip to main content
Glama

run_shortcut

Destructive

Executes a named macOS Shortcut, waits up to 120 seconds, and returns text output; optional text input can be passed to automate the requested task.

Instructions

Run a shortcut by name and wait for it (up to 120 seconds). A shortcut can do anything on this Mac, so run only what the user asked for. It can take text as 'input'. Text output is returned. Other output types are only described by type and size.

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": {
      "name": "<name>"
    },
    "name": "run_shortcut"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesShortcut name from list_shortcuts. Ignores case.
inputNoText to give the shortcut as input.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true, and the description adds genuinely new context on top: a concrete 120-second blocking timeout, the fact that arbitrary side effects on the Mac are possible, and how return values behave (text returned; other types only described by type and size). The only gap is what happens on timeout or failure, which is not stated. Minor tension exists between "can do anything on this Mac" and openWorldHint=false, but this is a nuance rather than a direct contradiction of the destructive-write profile.

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?

Three short sentences, each earning its place: what it does and blocks, the safety caveat, then input/output shape. The most decision-relevant facts (action, timeout, caution) are front-loaded.

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?

With no output schema, the description correctly compensates by explaining that text output is returned and non-text outputs are reduced to type and size — critical for an agent deciding whether to call this. Timeout behavior is covered; error/failure semantics and the 120-second cap's consequences are not.

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%, so both parameters — name (case-insensitive, from list_shortcuts) and input text — are already documented. The description adds only that input is text-typed, which is essentially redundant with the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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

Purpose4/5

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

States a specific verb and resource ("Run a shortcut by name") plus scope details: it blocks and waits up to 120 seconds. An agent immediately knows this is an execution tool, not a listing tool. It stops short of 5 because there is no sibling execution tool to be distinguished from, so the differentiation language is absent by necessity.

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

Usage Guidelines3/5

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

"run only what the user asked for" is a real constraint on when to invoke, and the schema points at list_shortcuts for name discovery. But there is no explicit routing guidance — nothing says when to prefer this over a dedicated tool (e.g., use create_note rather than a shortcut that creates notes), which matters given the siblings cover notes, mail, and calendars.

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