@proof-holdings/mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

update_webhook_endpoint

Destructive

Update a webhook endpoint's URL, events, scope, sub-accounts, status, or description to route event deliveries correctly. Change only the fields you need; the signing secret stays unchanged.

Instructions

Update a webhook endpoint: its URL, events, scope, sub-accounts, status or description. Every field is optional, but send at least one. Changing the scope to "selected" without profile_ids keeps the stored list. The signing secret is unchanged (rotate it with rotate_webhook_endpoint_secret).

ACCESS: needs a Proof account. Set PROOF_API_KEY and restart this server, then call this tool again. start_login does NOT open this tool.

Input Schema

Name	Required	Description
`id`	Yes	Webhook endpoint ID
`url`	No	HTTPS URL deliveries are sent to, at most 2000 characters. Private, loopback and link-local addresses are refused.
`scope`	No	"all" serves every sub-account, present and future, plus account-level events; "selected" serves only the sub-accounts in profile_ids
`events`	No	Subscription patterns (at most 32): an exact event type, a family wildcard such as "proof.", or "". An empty list means every event.
`status`	No	A disabled endpoint receives nothing
`description`	No	Your own label for the endpoint, at most 200 characters; null clears it
`profile_ids`	No	Sub-account ids, 24 hex characters each, at most 100. At least one when scope is "selected"; none when scope is "all".

Output Schema

Name	Required	Description
`id`	No	MongoDB ObjectId
`url`	No	HTTPS URL deliveries are POSTed to, at most 2000 characters. Private, loopback and link-local addresses are refused.
`scope`	No	`all` — every sub-account, present and future, plus account-level events. `selected` — only the sub-accounts in `profile_ids`; account-level events never reach it.
`events`	No
`legacy`	No	The endpoint converted from the account's single webhook URL — the one the deprecated `/me/settings` webhook block reads and writes.
`status`	No	A `disabled` endpoint receives nothing; its history and secret are kept.
`created_at`	No
`secret_set`	No	Whether the endpoint has a signing secret (always true).
`updated_at`	No
`description`	No
`profile_ids`	No

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.7.2Nov 6, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already flag destructiveHint=true and readOnlyHint=false, yet the description still adds real behavioral context: partial updates leave unset fields intact, the stored profile list survive an omitted profile_ids when scope is "selected", and the signing secret is untouched by an update. It doesn't explain why the operation is marked destructive (e.g. what a scope change to "all" discards), which is the one gap given that annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The mutable fields and the at-least-one constraint are front-loaded, followed by the two non-obvious edge cases, then a discrete ACCESS block. Every sentence is load-bearing, including the explicit warning that start_login will not unlock this tool.

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?

An output schema exists so return values need no explanation, and annotations cover the safety profile. Given 7 parameters and a destructive update, the description supplies the missing pieces: optionality, inter-field behavior, the secret boundary, and the auth prerequisite.

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, and the description earns above that by documenting cross-parameter behavior the schema cannot express: the scope/profile_ids coupling and the at-least-one-field rule. It doesn't add format detail for individual fields, but the schema already carries that.

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?

Opens with a specific verb plus resource ("Update a webhook endpoint") and enumerates the mutable surface: URL, events, scope, sub-accounts, status, description. An agent can immediately tell this apart from rotate_webhook_endpoint_secret or create_webhook_endpoint 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 a clear operating condition ("Every field is optional, but send at least one") and routes secret rotation to the named sibling rotate_webhook_endpoint_secret. It also states the access prerequisite. It stops short of saying when to prefer this over, say, delete_webhook_endpoint or when an update is inappropriate, but the practical guidance is well above average.

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

Deploy Server