Skip to main content
Glama
Upload-Post

Upload-Post

Official

Test a webhook subscription

test_webhook_subscription

Send a signed sample event to a webhook subscription to verify delivery, with a preview first and confirmation required before sending.

Instructions

Send one signed sample event to a subscription now, with the keys of the real event and test: true. ok is true when the destination answered with a status below 400 (a redirect counts as delivered). Logged as a test delivery: never retried and never counted towards disabling the subscription. 409 subscription_disabled or blocked_url; 400 invalid_event when event is not one of the subscription's events. Not generally available yet: until webhook subscriptions are switched on for the account, every call answers 503 with reason webhook_subscriptions_disabled (the feature is off, not a temporary failure). Needs the user's approval: call it first without confirmed to get a preview (nothing is sent), show the user exactly what will go out, and repeat the call with confirmed: true only after they approve.

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": {
      "subscription_id": "<subscription_id>"
    },
    "name": "test_webhook_subscription"
  }
}

Input Schema

NameRequiredDescriptionDefault
eventNoWhich of the subscription's events to sample. Default: its first event.
confirmedNoSet to true only after the user has seen the preview this tool returns without it and approved it. Without it nothing is sent.
subscription_idYesSubscription id (`whsub_...`) from list_webhook_subscriptions or create_webhook_subscription.

Output Schema

NameRequiredDescriptionDefault
resultNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.26.5

TDQS

A4.6/5.0
Behavior5/5

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

Adds substantial behavior beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false): the event is logged as a test delivery, never retried, and never counted toward disabling the subscription; a redirect counts as delivered; the account-level 503 feature gate is distinguished from a transient failure. Error codes 409 subscription_disabled/blocked_url and 400 invalid_event are enumerated, which the annotations cannot convey.

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 the delivery outcome, then the side effects, then errors, then the approval flow — a sensible order with almost no filler. It is a dense single paragraph, though; the error-code and approval details would scan faster as separated clauses.

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?

Complete for a 3-parameter mutation tool: prerequisites (feature flag), approval workflow, side-effect semantics, and failure modes are all covered. An output schema exists, yet the description still explains what `ok` means, which is the one return detail an agent needs to act on.

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 baseline is 3, but the description adds meaning: `confirmed` gates an actual send and the no-`confirmed` call sends nothing, and `event` must be one of the subscription's events or the call returns 400 invalid_event. That constraint goes beyond the schema's "Default: its first event."

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 and resource ("Send one signed sample event to a subscription now") and immediately distinguishes the payload from a real one ("keys of the real event and `test: true`"). An agent can tell this apart from real delivery/redeliver tools without opening the schema.

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 an explicit procedural rule: call without `confirmed` to preview, show the user, then repeat with `confirmed: true` only after approval. It also flags the pre-GA state where every call returns 503, which prevents pointless retries. It does not name sibling alternatives (e.g. redeliver_webhook) or contrast test vs. real delivery paths, so it stops short of full alternative routing.

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

Deploy Server

Other Tools