Skip to main content
Glama

sockdock_save_rule

Destructive

Create or update Slack automation rules that run agents or programs from posts, validating channel, folder, and executable settings before saving and reporting fixes for any errors.

Instructions

Adds a rule (omit name) or changes one (give its name; fields you omit keep their values). SockDock checks it like its own form: the channel must be one the Slack app is in, the folder must exist, and a program must be an executable file. If there are problems nothing is saved and each problem says how to fix it. A new rule goes to the bottom of its channel and gets a name like rule-4 (returned). To clear a field pass "" or []; null or leaving it out keeps it. Settings the form does not show (other allowed tools, a prompt file) are kept. args are split like a shell command line (quotes group words). The user gets a notification on their Mac. Anyone who can post in the channel can trigger the rule unless allowed_users lists member IDs (find them with sockdock_find_users; [] opens the rule to everyone again). For channel dm the rule reacts to DMs to the Slack app from anyone in the workspace; a new DM rule without allowed_users is limited to the owner (if nobody is registered, you must say who). mention_only: true makes a channel rule run only for posts that mention the Slack app. Posts and thread replies from people not listed are ignored without a reply. If the rule is open to everyone and lets the agent run commands or edit files, the result has a warning: tell the user. An agent rule can always read files in its folder; set allow_web, allow_edit and allowed_commands only to what the task needs, and avoid combining allow_edit with allowed_commands in channels the user does not fully trust. A program gets the post as JSON on stdin and its stdout is the reply (see the server guide for the JSON). Examples: {"channel": "#dev-help", "condition_type": "starts_with", "keyword": "review", "runs": "agent", "folder": "/projects/web-app", "instructions": "Review the files named in the post and reply with short findings.", "allowed_commands": ["npm test"]} {"channel": "#ask", "condition_type": "all_posts", "runs": "agent", "folder": "/notes"} (every post in #ask starts a run) {"channel": "#ops", "condition_type": "starts_with", "keyword": "ping", "runs": "program", "program": "/bin/ping.sh"} {"name": "rule-3", "keyword": "deploy"} {"name": "rule-3", "allowed_users": ["U0123ABCD"]} (only that person may run rule-3) {"channel": "dm", "condition_type": "starts_with", "keyword": "todo", "runs": "agent", "folder": "/notes"} (DMs starting with todo; only the owner) {"channel": "#dev-help", "condition_type": "all_posts", "mention_only": true, "runs": "agent", "folder": "~/projects/web-app"} (posts that mention the Slack app)

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": "sockdock_save_rule"
  }
}

Input Schema

NameRequiredDescriptionDefault
argsNoprogram: arguments
nameNothe rule to change; omit to add a rule
runsNoagent (default for a new rule) or program
agentNofor runs agent: claude_code (default) or codex
modelNoagent: for claude_code opus, sonnet or haiku; for codex a Codex model name; empty for the default
folderNoworking folder (absolute or ~/...); for a program, defaults to the program's folder
channelNochannel name (#dev-help or dev-help) or ID; must be in sockdock_list_channels. dm for DMs to the Slack app
keywordNothe keyword, or the regular expression (RE2) for match; not used for all_posts
programNoprogram: path to the executable; gets the post as JSON on stdin, its stdout is the reply
allow_webNoagent: may search and fetch the web
allow_editNoagent: may edit files in the folder
timeout_secNotime limit in seconds; 0 for the default (600 for agents, 300 for programs)
instructionsNoagent: instructions added to its system prompt
mention_onlyNotrue to run only for posts that mention the Slack app (@app); not used for dm
allowed_usersNomember IDs (U…, from sockdock_find_users) of the only people who may run the rule; [] lets everyone in the channel run it; omitted on a new rule means everyone
condition_typeNostarts_with (default for a new rule), contains, match or all_posts
allowed_commandsNoclaude_code only: command prefixes it may run, e.g. 'npm test'. Not for codex, which always runs commands in its sandbox

Output Schema

NameRequiredDescriptionDefault
okYes
nameNo
warningNosaved, but tell the user this
problemsNowhat to fix, per field (nothing was saved)
config_problemsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare destructiveHint=true and openWorldHint=false, and the description is consistent with a mutating, local-only tool. Beyond the annotations it adds genuinely useful behavior: validation blocks all saves on error, omitted fields retain values while "" or [] clears them, new rules append to the bottom of the channel and get a generated name, and the user receives a Mac notification. That is solid added context, though the score stays mid-range because much of the text is rule-domain policy rather than disclosure of what this call itself destroys or overwrites (e.g., it never states that an existing rule's settings can be silently altered by a partial save).

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?

The core save semantics are front-loaded in sentence one, followed by validation, defaults, then permission guidance. It is dense and long, but nearly every sentence carries actionable detail, and the seven worked examples efficiently encode parameter combinations that prose would take far longer to convey.

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 17-parameter mutation tool with no required fields and an output schema, the description covers creation, modification, clearing, validation, defaults, permission model, and security warnings. The only real omission is how this tool relates to sockdock_check_rule/sockdock_test_match for validating a rule shape before saving.

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

Parameters5/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, but the description adds real meaning the schema cannot express: args are split like a shell command line with quoting, "" vs [] vs null/omitted have distinct clearing semantics per field, allowed_users [] reopens the rule to everyone, and mention_only is meaningless for dm. It also explains cross-parameter interactions (dm rules default to owner-only without allowed_users; program folder defaults to the program's folder).

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?

"Adds a rule (omit name) or changes one (give its name)" states a specific verb and resource and resolves the create-vs-update ambiguity that would otherwise be the main selection risk. It also names concrete downstream references (sockdock_find_users, sockdock_list_channels) so the agent knows where prerequisite data comes from.

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?

Gives strong operational context: omit name to add, supply name to change, validation failure means nothing is saved, and explicit when-not guidance such as "avoid combining allow_edit with allowed_commands in channels the user does not fully trust" and "set allow_web, allow_edit and allowed_commands only to what the task needs." It never routes the agent to a sibling such as sockdock_check_rule for dry-run validation, which is the one gap keeping it from a 5.

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