Sergio by Serviche

Change how a flow starts

set_flow_start

Idempotent

Changes how one of this business's flows starts ("Starts when" in Automations) and whether it is on, exactly as the Automations editor's save does. starts_when "contact" means "You add it to a contact": nothing starts the flow by itself. Any other value starts it automatically on that booking event. Switching a start off ("contact") or turning a flow off (active false; its runs in progress end) is open to this seat. Starting a flow on an event or turning a flow on is owner-level: available only when the owner turned on "Let this agent change owner settings" for this seat; the owner is told about each such change. A flow that starts on every upcoming job (starts_when_words says so) turns on only after a person confirms how many jobs it covers, which this tool cannot do: it comes back refused with that count, and the owner turns it on in Automations. Picking a booking event here makes a flow start only on jobs from then on. read("flows") shows each flow and its current start. Events: booking_created (New job booked); booking_changed (Job changed); booking_cancelled (Job cancelled); staff_clocked_in (Cleaner clocked in); staff_not_clocked_in (Cleaner hasn't clocked in); job_finished (Job finished); visit_unconfirmed (Past job not marked done in the booking platform); card_declined (Card declined); review_received (Review received); review_low_rating (Low-star Google review); staff_on_the_way (Cleaner tapped On the way); staff_clocked_out (Cleaner clocked out); staff_running_late (Cleaner says they are running late); staff_not_on_the_way (Cleaner hasn't tapped On the way); staff_not_clocked_out (Cleaner hasn't clocked out); staff_clocked_in_twice (Cleaner clocked in on two jobs at once); staff_schedule_request (Cleaner asked to change their schedule). Pass the same idempotency_key when retrying; a repeat returns the original result.

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": {
      "flow_id": "<flow_id>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "set_flow_start"
  }
}

Input Schema

Name	Required	Description
`active`	No	true turns the flow on, false turns it off.
`flow_id`	Yes	The flow id (from read("flows")).
`starts_when`	No	"contact" for by hand only, or the booking event that starts it.
`justification`	No	Optional: why the business wants this. Shown to the owner with an owner-level change.
`idempotency_key`	Yes	Your id for this operation (8-128 of A-Z a-z 0-9 . _ : -). Reuse it on every retry of the same operation; use a new one for a new operation.
`first_booking_only`	No	With an event: true starts it only on a client's first booking. Omitted keeps the current choice.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 8, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Goes well beyond the annotations: discloses that turning a flow off ends its in-progress runs, that the owner is notified of each owner-level change, that setting an event only affects jobs from then on, and that a refusal returns a job count instead of applying the change. Idempotency behavior is restated in operational terms ('Pass the same idempotency_key when retrying; a repeat returns the original result'), matching idempotentHint=true without contradicting anything.

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: it leads with what the tool does, then permissions, then the edge case, then the event catalogue. Every sentence carries information, but it is delivered as one dense wall of prose and the event list is lengthy; light structuring would improve scanning without cutting content.

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 6-parameter mutation with no output schema, this covers everything an agent needs: prerequisites, permission tiers, side effects on running flows, the refused-path outcome, idempotency retry rules, and where to look up current state. Nothing material is left for the agent to guess.

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

Parameters4/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; the description earns above that by decoding what the enum values actually mean in business terms — the full event list with human-readable glosses (e.g. visit_unconfirmed = 'Past job not marked done in the booking platform') and the semantic weight of 'contact'. It adds little on justification, first_booking_only, or active beyond what the schema already says.

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: 'Changes how one of this business's flows starts' and 'whether it is on', tied to the Automations editor's save semantics. This is unambiguous about what is being mutated, but it never names or contrasts itself with the close sibling set_flow_on, leaving the agent to infer which of the two to call when it only wants to toggle active state.

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?

Explicitly distinguishes the two modes of starts_when ('contact' means nothing starts the flow by itself; any other value starts it automatically on that event) and states the permission boundary: turning a start or flow off is open to this seat, turning it on is owner-level. It also names the case where the tool cannot succeed at all ('A flow that starts on every upcoming job ... comes back refused with that count, and the owner turns it on in Automations') and points to read("flows") for the current state, so the agent knows both when to call and when to defer.

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

All Sergio by Serviche 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?