GetV1InstancesWebhookEndpointsSecretRetrieve the signing secret for a specific webhook endpoint in a BlindPay instance to verify incoming webhook payloads.
Retrieve Webhook Secret
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| instance_id | Yes |
Changes observed during successful MCP inspections.
v1.9.3Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond the title: it does not disclose that the response contains sensitive credential material, whether the secret is rotatable, whether retrieval is audited, or what happens if the endpoint has no secret configured.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three words with no padding and the verb-object ordering is front-loaded. Brevity here shades into under-specification rather than efficiency, since nothing else compensates for the missing detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool returning sensitive credential material with no output schema and entirely undocumented parameters, the description should explain what is returned and any handling caveats. As written, an agent knows only the resource name and must guess at the returned value's shape and semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for two required parameters, so the description carries the burden and supplies none of it. The schema gives only examples and 15-character length bounds for `id` and `instance_id`; the description never says that `id` is the webhook endpoint identifier rather than an instance-level or customer-level id, which is the likely point of confusion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Retrieve Webhook Secret" names a verb and a resource, so the basic intent is legible. But it does not distinguish this tool from its close siblings (GetV1InstancesWebhookEndpoints, GetV1InstancesWebhookEndpointsPortalAccess), nor clarify what a "secret" is here (signing key material vs. a webhook payload).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to call this instead of GetV1InstancesWebhookEndpoints for webhook configuration, and no mention of prerequisites such as permissions or the sensitivity of fetching a credential. An agent must infer everything from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.