mcp-server

Manage a workspace trigger (SFTP/AWS S3 pull, spec chaining, or schedule)

manage_trigger

Destructive

Create, list, update, delete, or fire a workspace job trigger. Four types:

"sftp"/"aws_s3": pulls files from a connection (sftp: remote server; aws_s3: S3 bucket/prefix) into an already-analyzed data spec on a schedule (hourly/daily/monthly, UTC). Type must match the connection's type; aws_s3 also requires s3Bucket (s3Prefix optional). Natural-language preRules (which files to pick up) and postRules (what to do after upload) are compiled into executable code server-side — never pass raw code. The connection must already exist and have passed test (see manage_connection). For a first-time "set up a daily/scheduled pull" request, prefer setup_scheduled_pull, which sets up the connection and trigger together.
"spec_success": fires a spec automatically whenever a DIFFERENT spec's job completes successfully (set upstreamSpecName to that spec). No connection/frequency. Use this when the request ties the run to another job finishing (e.g. "run this after the customers load finishes").
"schedule": fires a spec directly on a plain frequency (hourly/daily/monthly, UTC), no connection and no upstream spec. Use this when the request is time-based with no dependency (e.g. "run this every morning").

IMPORTANT: "spec_success" and "schedule" triggers can only target a table-source (sourceType: "tables") or compaction (sourceType: "compaction") spec (see onboard_data_source) — they have no file to load, only a generated query to re-run or a set of tables to compact. If asked to set up a scheduled/recurring job that reads from an already-loaded table (e.g. "keep a daily summary of the orders table up to date"), create that as an onboard_data_source sourceType "tables" spec first, THEN create the trigger here. Same for a recurring compaction — create the sourceType "compaction" spec first. Prefer "spec_success" when the user's phrasing implies "after X loads/finishes"; prefer "schedule" when they just want a cadence with no stated dependency; ask if genuinely ambiguous. For sftp/aws_s3, the referenced spec must already have been analyzed once (see onboard_data_source).

After firing a trigger (action "run-now") — or any one-off manual run — use action "run-history" to monitor its outcome: it starts as status: running and settles to success, failed, or no-files, with filesPulled and a message.

Input Schema

TableJSON Schema

Name	Required	Description
`type`	No	Trigger type. Optional for create (defaults to "sftp"). For sftp/aws_s3 must match the connection's type.
`action`	Yes	Which operation to perform.
`cursor`	No	run-history: opaque `nextCursor` from a prior page (omit for the first page).
`dedupe`	No	sftp/aws_s3 only. Required for create — ask the user rather than assuming a value; do not default it silently. Whether repeat pulls should skip files already loaded into this spec, matched by file name. Has real consequences: with dedupe true, a file that reappears under the same name (e.g. re-uploaded with corrected data) will be silently skipped; with dedupe false, an unchanged file left on the server will be reloaded every run. Omit only for update, where omitting leaves the trigger's existing setting unchanged.
`specId`	No	run-history: filter to runs of triggers feeding this spec.
`enabled`	No	Whether the trigger is active. Defaults to true on create.
`endTime`	No	run-history: ISO 8601 upper bound (inclusive) on when the run started.
`pageSize`	No	run-history: records per page (default 25).
`preRules`	No	sftp/aws_s3 only. Natural language: which files to pick up (e.g. "only *.csv under /outbound").
`s3Bucket`	No	aws_s3 only. Bucket to poll. Required for create when type is "aws_s3", or to change it on update. Each run lists at most 5000 objects from the bucket/prefix (oldest key first) — past that, new files can be missed. On create, a successful response includes a `warnings` array with this note; relay it to the user and suggest an S3 lifecycle rule to expire/transition old objects.
`s3Prefix`	No	aws_s3 only. Optional key prefix; defaults to the whole bucket.
`specName`	No	The spec this trigger fires. Required for create.
`frequency`	No	Required for create when type is "sftp", "aws_s3", or "schedule"; optional on update to change the schedule. Not applicable to spec_success.
`postRules`	No	sftp/aws_s3 only. Natural language: what to do after a file loads (e.g. "rename with .done suffix").
`startTime`	No	run-history: ISO 8601 lower bound (inclusive) on when the run started.
`triggerId`	No	Existing trigger. Required for update/delete/run-now/clear-processed-files.
`workspaceId`	No	Workspace to act on. Defaults to your only workspace if you have exactly one.
`connectionId`	No	sftp/aws_s3 only. Connection to pull from. Required for create when type is "sftp"/"aws_s3". Also usable as a run-history filter.
`upstreamSpecName`	No	spec_success only. The spec whose successful job completion fires this trigger. Required for create when type is "spec_success".

Output Schema

TableJSON Schema

Name	Required	Description
`runs`	No	action "run-history" only
`type`	No
`count`	No	action "list" only
`dedupe`	No
`specId`	No
`deleted`	No	action "clear-processed-files" only
`enabled`	No
`message`	No
`pageSize`	No	action "run-history" only
`preRules`	No
`s3Bucket`	No
`s3Prefix`	No
`specName`	No
`triggers`	No	action "list" only
`warnings`	No	action "create", type "aws_s3" only. Advisory notes, e.g. the 5000-object S3 listing cap — relay to the user.
`createdAt`	No
`createdBy`	No
`frequency`	No
`lastJobId`	No
`lastRunAt`	No
`postRules`	No
`triggerId`	No
`updatedAt`	No
`nextCursor`	No	action "run-history" only
`workspaceId`	No
`connectionId`	No
`lastRunStatus`	No
`upstreamSpecId`	No	type "spec_success" only
`upstreamSpecName`	No	type "spec_success" only

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedAug 21, 2026

changedInput schema / properties / s3Bucket / description

Previous value: -"aws_s3 only. Bucket to poll. Required for create when type is \"aws_s3\", or to change it on update."New value: +"aws_s3 only. Bucket to poll. Required for create when type is \"aws_s3\", or to change it on update. Each run lists at most 5000 objects from the bucket/prefix (oldest key first) — past that, new files can be missed. On create, a successful response includes a `warnings` array with this note; relay it to the user and suggest an S3 lifecycle rule to expire/transition old objects."

addedOutput schema / properties / warnings

Added value: +{
+  "description": "action \"create\", type \"aws_s3\" only. Advisory notes, e.g. the 5000-object S3 listing cap — relay to the user.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed3 schema fields changedAug 19, 2026
- addedInput schema / properties / action / description
```
Added value: +"Which operation to perform."
```
- addedInput schema / properties / enabled / description
```
Added value: +"Whether the trigger is active. Defaults to true on create."
```
- addedInput schema / properties / frequency / properties / unit / description
```
Added value: +"Schedule cadence."
```
First observedAug 19, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Despite annotations already indicating destructive and non-idempotent behavior, the description adds substantial context: natural-language rules are compiled server-side and raw code is never accepted, connections must already exist and have passed test, aws_s3 lists at most 5000 objects per run, dedupe has real data-loading consequences, and run-history statuses settle to success/failed/no-files. This exceeds what annotations alone would provide.

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 description is long, but the length is justified by four distinct trigger types, 19 parameters, and multiple important caveats. It is well-structured with type-labeled sections and important callouts. It loses one point only because a few points, such as the run-history monitoring advice, could have been tightened without losing value.

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 high-complexity tool with many parameters and sibling relationships, the description covers prerequisites, per-type rules, exclusions, post-run monitoring, and alternatives. The presence of an output schema means return values do not need to be re-explained, and nothing critical needed to call this tool correctly is missing.

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%, but the description adds meaning beyond the schema by explaining which type is required for which parameters, that dedupe must be asked of the user rather than assumed, that s3Bucket has a 5000-object caveat, and that frequency is required for create for sftp/aws_s3/schedule but not spec_success. This materially enriches the bare schema definitions.

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?

The description opens with a specific verb and resource: 'Create, list, update, delete, or fire a workspace job trigger.' It then cleanly differentiates the four trigger types and explicitly distinguishes this tool from setup_scheduled_pull, so an agent can tell them apart.

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

Usage Guidelines5/5

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

Usage guidance is extensive and prescriptive: it says to prefer setup_scheduled_pull for first-time daily/scheduled pulls, prefer spec_success when the request is tied to another job finishing, prefer schedule for plain cadence, and ask if genuinely ambiguous. It also routes the user to onboard_data_source when a table-source or compaction spec must be created first.

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

All mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?