Skip to main content
Glama
nerdit-ai

Nerdit

Official
by nerdit-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

add_hook

Creates an inbound webhook address for a deployed app, verifies each delivery's signature, and forwards provider headers and exact body to the specified app path; returns URL and secret key.

Instructions

Give a deployed app an inbound webhook address a provider can POST to.

    The machine verifies each delivery's signature before the app sees it,
    then POSTs the provider's headers and exact body to ``path``. No secret
    travels through this tool: the response carries ``url`` (paste it at the
    provider) and ``secret_key``; then store the provider's signing secret
    with ``set_secret(name, {secret_key: value})``. ``url`` is null until
    the machine is linked, and answers only once the app is shared.

    Refusals: 422 ``hook.invalid`` (``reason`` ``name`` or ``shape``), 422
    ``hook.kind_unsupported`` (models and databases), 409 ``hook.exists``
    (a different webhook already has that name). A replay of the same
    webhook answers ``created: false``.

Input Schema

NameRequiredDescriptionDefault
nameYesName (or row id) of an existing deployed app — only kind 'service' can be exposed: ``share_service``/``add_domain`` refuse a model or database with 422 ``*.kind_unsupported``, while the remove tools just find nothing to undo.
pathYesApp path each delivery is POSTed to, e.g. ``/webhooks/stripe``.
headerNosender ``hmac`` only (required there): the signature header.
prefixNosender ``hmac`` only: text before the hex digest (``sha256=``).
senderYesWho signs the deliveries: ``stripe`` (Stripe-Signature), ``github`` (X-Hub-Signature-256), ``slack`` (X-Slack-Signature), ``hmac`` (HMAC-SHA256 lowercase hex in ``header``, after ``prefix``) or ``none`` (unsigned: the URL is the only guard).
hook_nameYesWebhook name: lowercase letters, digits and '-', 1-32 characters, starting with a letter (e.g. ``stripe``); maps to ``NERDIT_HOOK_<NAME>_SECRET`` and ``NERDIT_HOOK_<NAME>_URL``.
idempotency_keyNoCaller-chosen key: a retry with the same key replays the first result instead of acting twice. Omit and a fresh key is minted per call, so each call acts.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

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

With no annotations, the description carries the full behavioral burden and does so well: it explains that the machine verifies each delivery's signature before the app sees it, forwards the provider's headers and exact body to path, and that no secret travels through this tool. It also discloses prerequisites, null URL behavior, refusal codes, and idempotent replay semantics.

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 description is front-loaded with the purpose, then explains the delivery behavior, secret handling, prerequisites, and refusals in a compact sequence. Despite its density, every sentence contributes operational information an agent needs.

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 mutation tool with no annotations and no output schema, the description is complete enough: it covers the creation workflow, signature verification, returned url and secret_key, sharing and linking prerequisites, refusal modes, and replay behavior. An agent has what it needs to call add_hook correctly.

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%, so the schema already explains all parameters, including sender values and header/prefix conditions. The description adds some workflow meaning around path and the returned secret_key, but does not add parameter-specific semantics beyond what the schema provides.

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?

The description states a specific verb and resource: give a deployed app an inbound webhook address that a provider can POST to. It clearly distinguishes this from siblings like list_hooks, remove_hook, and set_secret by describing the creation workflow and the follow-up secret-storage step.

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?

It gives strong usage context: only deployed service apps can be exposed, models and databases are refused, the app must be shared, and the machine must be linked before a URL appears. It also routes the follow-up signing-secret storage to set_secret, though it does not explicitly say when to use list_hooks or remove_hook for existing hooks.

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