Skip to main content
Glama

agents_simulate_inbound

Read-onlyIdempotent

Replay an inbound message on a thread through the real trigger pipeline and return what would have happened. The router auto-picks the winning enabled agent + trigger by priority/specificity (same logic as production). By default send_mode='draft' so no real message is sent; pass send_mode='auto' on a test account to let the matched agent actually deliver (drafts get overwritten by the next draft, so 'auto' is the only way to verify Telegram/email delivery end-to-end).

Use to verify routing for a thread: which agent answers, which trigger wins, or — when nothing matches — the structured skip reason. Pass blockchain_tx_data instead of message_text to simulate a wallet event on the thread.

Returns: {matched: true, matched_agent: {id, name, execution_mode}, matched_trigger: {id, trigger_type, conditions, specificity_score}, routing_reason, response_text, messages[], execution_mode, send_mode, model_used, tokens_input, tokens_output, latency_ms, } on a hit, or {matched: false, skip_reason, simulator_warnings} on a miss.

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

Input Schema

NameRequiredDescriptionDefault
send_modeNoHow the matched agent should deliver its reply. 'draft' (default, safe) creates a draft only — no real send, no idempotency key. 'auto' lets the agent deliver through the channel adapter exactly as it would in production — use this on a test account to verify Telegram/email delivery end-to-end. Drafts get overwritten by the next draft on the thread, so 'auto' is required when you want to see the message persisted.draft
thread_idNoThread ID to route the simulated event from. Must belong to the API key's workspace. Omit and set create_new_livechat=true to test on a FRESH thread with no history.
in_workspaceNoRun this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected.
message_textNoInbound message body to simulate. Defaults to '[MCP simulation test]' when omitted.
system_messageNoTag the simulated inbound as a system/service-message row (missed call, group join, pinned message, etc.) so the `excluded_system_message_kinds` trigger filter can be exercised end-to-end. Shape: {"category": <one of call_event | membership_change | contact_signup | pinned_message | chat_metadata_change | voice_chat_event | other_service>, "native_kind": <free-form upstream event class name, e.g. 'MessageActionPhoneCall'>}. The category is written into `message.meta.system_message` (mirroring the real Telegram ingest path) AND surfaced on the synthetic IncomingEvent so the trigger evaluator honors the block-list. Omit for a normal text-message simulation.
blockchain_tx_dataNoWhen set, simulate a wallet event (what a blockchain_event trigger receives) instead of a channel:message:new event. Keys: event_kind (transfer_in, transfer_out, risk_level_up, sanctioned, frozen), chain, address, and for a transfer transfers: [{token, amount, value_usd, counterparty, tx}].
channel_account_idNoOptional. The livechat widget's channel_account_id to host the fresh chat when create_new_livechat=true. Omit to auto-pick the workspace's active livechat widget.
attachment_file_idsNoOptional list of workspace file IDs to attach to the simulated inbound message — same shape as a real Telegram message with image/document attachments. Use this to test agent behavior on incoming messages that carry images (e.g. logos for invoices) or documents the agent must reference. File IDs must belong to the API key's workspace.
create_new_livechatNoStart a FRESH, history-free livechat chat instead of using an existing thread_id — creates a new visitor + thread on the workspace's livechat widget and routes your message onto it. The response's thread_id is the new thread; pass it back (with send_mode='auto') to continue the conversation. Ideal for clean multi-turn text tests. OMIT to reuse an existing thread_id. Ignored if thread_id is given.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / blockchain_tx_data / description
      Previous value: -"When set, simulate a blockchain:transfer event instead of a channel:message:new event. Expected keys: chain, to_address / from_address, tx_hash."New value: +"When set, simulate a wallet event (what a blockchain_event trigger receives) instead of a channel:message:new event. Keys: event_kind (transfer_in, transfer_out, risk_level_up, sanctioned, frozen), chain, address, and for a transfer transfers: [{token, amount, value_usd, counterparty, tx}]."
  2. Changed1 schema field changed
    • addedInput schema / properties / in_workspace
      Added value: +{
      +  "description": "Run this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected.",
      +  "type": "integer"
      +}
  3. Added
  4. Removed
  5. Changed1 schema field changed
    • changedInput schema / properties / create_new_livechat / description
      Previous value: -"Start a FRESH, history-free livechat chat instead of using an existing thread_id — creates a new visitor + thread on the workspace's livechat widget and routes your message onto it. The response's thread_id is the new thread; pass it back (with send_mode='auto') to continue the conversation. Ideal for clean multi-turn text tests. Ignored if thread_id is given."New value: +"Start a FRESH, history-free livechat chat instead of using an existing thread_id — creates a new visitor + thread on the workspace's livechat widget and routes your message onto it. The response's thread_id is the new thread; pass it back (with send_mode='auto') to continue the conversation. Ideal for clean multi-turn text tests. OMIT to reuse an existing thread_id. Ignored if thread_id is given."
  6. Changed4 schema fields changed
    • addedInput schema / properties / channel_account_id
      Added value: +{
      +  "description": "Optional. The livechat widget's channel_account_id to host the fresh chat when create_new_livechat=true. Omit to auto-pick the workspace's active livechat widget.",
      +  "type": "integer"
      +}
    • addedInput schema / properties / create_new_livechat
      Added value: +{
      +  "description": "Start a FRESH, history-free livechat chat instead of using an existing thread_id — creates a new visitor + thread on the workspace's livechat widget and routes your message onto it. The response's thread_id is the new thread; pass it back (with send_mode='auto') to continue the conversation. Ideal for clean multi-turn text tests. Ignored if thread_id is given.",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / thread_id / description
      Previous value: -"Thread ID to route the simulated event from. Must belong to the API key's workspace."New value: +"Thread ID to route the simulated event from. Must belong to the API key's workspace. Omit and set create_new_livechat=true to test on a FRESH thread with no history."
    • changedInput schema / required
      Previous value: -[
      -  "thread_id"
      -]New value: +[]
  7. First observed

TDQS

B3.4/5.0
Behavior1/5

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

The description discloses real side effects — send_mode='auto' delivers live messages, drafts are overwritten, and create_new_livechat 'creates a new visitor + thread' — which directly contradicts readOnlyHint=true and idempotentHint=true in the annotations. It is informative about behavior, but the stated behavior conflicts with the declared safety profile, which is exactly the condition the rubric scores at 1.

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 default-safe behavior, then a usage paragraph, then the return shape — a sensible ordering. Some content is duplicated from the schema (draft-vs-auto and the draft-overwrite caveat appear in both places), which is the main trimming opportunity.

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 9-parameter, nested-object tool with no output schema, the description supplies the return shape for both hit and miss cases, explains the routing logic (priority/specificity), and covers the fresh-thread and wallet-event paths. An agent has enough to call it correctly without opening the schema.

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% and each of the 9 parameters is already documented in detail in the schema (send_mode semantics, system_message shape, blockchain_tx_data keys). The description adds only one cross-parameter hint ('pass blockchain_tx_data instead of message_text'), so the baseline 3 applies.

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 ('Replay an inbound message on a thread through the real trigger pipeline') plus the outcome ('return what would have happened'), and frames it as a routing verification tool. The purpose is unambiguous, though no sibling tool is named to anchor the boundary (e.g. versus agents_traces_list, which shows what actually happened).

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?

Explicitly says when to use it ('Use to verify routing for a thread: which agent answers, which trigger wins, or the structured skip reason') and gives conditional guidance for draft vs auto, thread_id vs create_new_livechat, and blockchain_tx_data vs message_text. It stops short of naming when-not-to-use or a sibling alternative for read-only inspection of past routing.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.