Shortcut Management

Beyond the library table view, Shortcuts Toolbox provides a rich detail view for each shortcut.

Shortcut Detail View

• Full metadata display — See all metadata including name, folder, action count, creation date, and more
• JSON structure view — Inspect the raw shortcut structure
• Run with parameters — Execute the shortcut directly, optionally passing input parameters
• Scoped dependency graph — View the dependency graph centered on this shortcut
• AI explanation — Let the AI analyze and explain what a shortcut does
• Execution history — View all past runs of the shortcut with their results in the Audit Log
• AI settings — Configure visibility, executability, and privacy per shortcut
• iCloud link generation — Generate shareable iCloud links for your shortcuts

Input and output schema comments

A shortcut can describe its own input and output. Add a Comment action whose text starts with Input Schema: and put a JSON Schema (draft-07) object under it. Do the same with Output Schema: for what the shortcut returns. Shortcuts Toolbox reads both the next time the shortcut’s contents are synced.

A few rules about how the comments are read:

• The first comment that matches wins. Later ones with the same prefix are ignored.
• The prefix is matched without regard to case, so input schema: works too.
• You can wrap the JSON in a ```json fence if you prefer.
• The top-level type can be object, string, number, integer, boolean or array. A plain type such as string means the shortcut takes one plain value, not JSON.
• If the JSON does not parse, the shortcut page shows a warning, and so does get_shortcut_details. The shortcut then behaves as if it had no schema.

Once a schema is in place, it drives three things:

• The run form. The run form on the shortcut’s page, and the Run tab for a device under Settings → Remote Execution, show a Form / Raw toggle. Form shows one field per property. Raw is the free-text box with input history. A property’s description becomes its help text, enum becomes a dropdown, and format: "multiline" gives it a larger text area.
• Validation. Input that does not match the schema is refused before the shortcut runs. This applies to the run forms, the run API routes, and the run_enabled_shortcut and run_remote_shortcut MCP tools. The error names each field that failed.
• AI tools. MCP clients and the in-app AI chat see both schemas when they list shortcuts, so they know what to send and what comes back. When the shortcut is exposed as its own tool (below), each property becomes a typed argument and its description becomes the argument’s description.

Expose as its own tool

By default, MCP clients and the AI chat reach your shortcuts through list_enabled_shortcuts and run_enabled_shortcut. That keeps the tool list short, but the AI has to look a shortcut up before it can run it. For shortcuts you call often, turn on Expose as its own tool under the shortcut’s AI settings, next to Enable for Chat/MCP.

• The shortcut is published as a standalone tool named shortcut_ plus its name in lower case with underscores. Things Task PATCH becomes shortcut_things_task_patch.
• The tool’s arguments come from the Input Schema. An object schema gives one argument per property. A plain type gives a single input argument. No schema gives an optional input argument. The Output Schema is listed as the tool’s output.
• It needs Enable for Chat/MCP on and an AI tool description. The description becomes the tool’s description.
• When Run on remote device is on, a Runs on choice appears: Server, Remote device, or Either. Either adds an optional device argument. Leaving it out runs the shortcut on this Mac.
• The MCP tool list updates as soon as you change the setting. No reconnect needed.

The setting is off by default, so enabling many shortcuts for Chat/MCP does not flood a client with tools. Shortcuts without it stay reachable through run_enabled_shortcut and run_remote_shortcut. The AI can also turn it on for you through request_update_shortcut_ai_settings, which asks you to confirm first.