RunWhen Platform MCP

Create Chat Command

create_chat_command

Create a chat slash-command with defined content and scope, optionally scheduling it via cron to deliver results to email or Slack.

Instructions

Create a chat command (slash-command). Name must be alphanumeric, underscore, or hyphen only.

Skill: runwhen-skill://manage-commands (scoping, scheduling, sinks).

Commands are invoked in chat as /label.

To run a command on a schedule, set cron_schedule plus sink_configs, run_as_user, and assistant_name. Results are delivered to each sink (email or Slack) when the cron fires.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	Yes	Command name (alphanumeric, underscore, or hyphen only).
`max_runs`	No	Maximum scheduled runs before the schedule stops (omit for unlimited).
`scope_id`	No	Scope ID (null for platform; workspace name for workspace).
`is_active`	No	Whether the command is active.
`scope_type`	Yes	One of platform, org, workspace, persona, user.
`description`	No	Optional description for the command.
`run_as_user`	No	Email of the user the scheduled session runs as. Required when cron_schedule is set.
`sink_configs`	No	Delivery targets when cron_schedule is set. Each entry: {type: 'email'\|'slack', mode: 'user'\|'all-workspace-users'\|'channel'\|'webhook', target: '...'}.
`cron_schedule`	No	Cron expression to run this command on a schedule (e.g. '0 8 * * 1-5'). When set, also provide sink_configs, run_as_user, and assistant_name.
`assistant_name`	No	Persona for scheduled runs (workspace prefix optional). For persona-scoped commands, must match scope_id (full form after PAPI). For workspace-scoped commands, use the short name (persona_name for chat).
`workspace_name`	Yes	The workspace to create the command in (e.g. 't-oncall').
`command_content`	Yes	Markdown content of the command.
`schedule_paused`	No	When true, the cron does not fire (independent of is_active).
`auto_approve_readonly`	No	When true, scheduled runs auto-approve read-only task execution (write tasks still require approval).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Jul 7, 2026

TDQS

A3.7/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the scheduled-run behavior and its dependency set (cron fires → results delivered to each sink), which is genuinely useful. It stops short of permissions/authorization requirements, what happens on name collision, or side effects, so the mutation semantics remain only partially transparent.

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 action and naming rule, then the skill reference, then the scheduling clause. The final sentence largely duplicates the cron_schedule parameter description, so it is slightly redundant but still tight overall.

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 14-parameter create tool with an output schema available, the description covers the primary workflow, the naming rule, and the scheduled-run path, and it routes to a skill for deeper scoping/scheduling detail. Missing only permissions and error/collision behavior, which keeps it from a 5.

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 the schema already documents all 14 parameters in detail. The description restates the cron_schedule dependency chain rather than adding format or edge-case detail beyond the schema (e.g., valid cron dialect, sink config shape). Baseline 3 is correct when the schema does the heavy lifting.

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 (Create) and resource (chat command / slash-command), and the naming constraint plus the invocation syntax [/label](cmd://name) make it unmistakable. The verb alone cleanly distinguishes it from sibling CRUD tools (get_chat_command, update_chat_command, list_chat_commands, delete-style operations).

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?

It gives one concrete usage conditional ("To run a command on a schedule, set cron_schedule plus sink_configs, run_as_user, and assistant_name") and points to a skill for scoping/scheduling/sinks. However, it never says when to prefer this over siblings like update_chat_command, nor any prerequisites (permissions, existing scope) for creation.

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

Deploy Server