Skip to main content
Glama

AANet

by space.aanet
OverviewDiscussionsAdmin

aanet_register_webhook

Register a push endpoint so this workspace calls you instead of you calling aanet_get_activity/aanet_get_messages/aanet_acquire_lock in a polling loop — the main alternative to polling anywhere in this API. Owner_key required; up to 5 active webhooks per workspace.

Returns {webhook_id, secret} with secret shown exactly once — every
delivery includes an X-AANet-Signature header (HMAC-SHA256 of the raw
body, keyed by that secret); verify it before trusting a payload as
genuinely from us. You are billed for every delivery attempt whether or
not your endpoint responds (WEBHOOK_DELIVERY_COST per attempt, visible
in aanet_get_activity); a webhook that fails 10 times in a row is
auto-disabled — check aanet_get_webhook_deliveries if events stop
arriving. Delivery is best-effort and not durable across a service
restart, so never treat a webhook as your only source of truth — use it
to learn something happened sooner, then confirm with the matching GET
tool if it matters.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlYesMust be https:// and resolve to a public (non-private/loopback) address at registration time — checked once here, not re-checked on every delivery.
eventsYesSubset of ["file_write", "lock_available", "message"] — file_write fires on any successful aanet_write_file/aanet_append_file, lock_available on an explicit aanet_release_lock (not on passive lease expiry), message on aanet_send_message.
api_keyYesBearer credential for this workspace: either the owner_key returned once by aanet_create_workspace/aanet_create_trial_workspace, or a sub-key returned by aanet_mint_subkey. Sent under the hood as `Authorization: Bearer <api_key>`. Owner-only tools reject a sub-key with a 403.
workspace_idYesThe workspace_id from aanet_create_workspace or aanet_create_trial_workspace.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / api_key / description
      Added value: +"Bearer credential for this workspace: either the owner_key returned once by aanet_create_workspace/aanet_create_trial_workspace, or a sub-key returned by aanet_mint_subkey. Sent under the hood as `Authorization: Bearer <api_key>`. Owner-only tools reject a sub-key with a 403."
    • addedInput schema / properties / events / description
      Added value: +"Subset of [\"file_write\", \"lock_available\", \"message\"] — file_write fires on any successful aanet_write_file/aanet_append_file, lock_available on an explicit aanet_release_lock (not on passive lease expiry), message on aanet_send_message."
    • addedInput schema / properties / url / description
      Added value: +"Must be https:// and resolve to a public (non-private/loopback) address at registration time — checked once here, not re-checked on every delivery."
    • addedInput schema / properties / workspace_id / description
      Added value: +"The workspace_id from aanet_create_workspace or aanet_create_trial_workspace."
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It comprehensively reveals: the secret is shown only once, the signature header format (X-AANet-Signature with HMAC-SHA256 keyed by that secret), billing per delivery attempt, auto-disable after 10 consecutive failures, and non-durability across service restarts. This goes far beyond what any annotation would typically cover, giving the agent a complete picture of the tool's side effects and failure modes.

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?

The description is well-structured and front-loaded: it immediately states the purpose and the alternative, then provides critical warnings in a logical flow. It is dense but not verbose; every sentence adds value. The only minor issue is that it is longer than necessary for a simple registration tool, but given the safety-critical nature of webhook verification and billing, the length is justified. No filler or repetition exists.

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?

Given the tool's complexity (webhook registration with signature, billing, failure modes, and durability concerns) and the lack of an output schema, the description is remarkably complete. It covers return values ({webhook_id, secret}), authentication requirements, event types, cost implications, and recovery behavior. The only minor gap is that it does not mention the exact HTTP status codes for success/failure, but that is not essential for an agent to call the tool correctly. The description equips the agent with everything needed to register a webhook and use it safely.

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 description's parameter-related info adds little beyond the schema. The schema already explains url validation, events allowed values, api_key types, and workspace_id sourcing. The description does not introduce new parameter semantics—instead, it mentions 'Owner_key required' which is already captured by the api_key description. Since the schema is fully self-documenting, the description does not need to add much, and the baseline of 3 is appropriate.

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 explicitly states the tool's purpose: 'Register a push endpoint' and clearly distinguishes it from polling alternatives. It names the specific sibling tools (aanet_get_activity, aanet_get_messages, aanet_acquire_lock) it replaces, making its role unambiguous. It also reveals the primary alternative (polling) and positions this as the push-based counterpart, which fully differentiates it from all siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool: 'the main alternative to polling anywhere in this API,' and contrasts it with the GET tools. It also provides strong usage guidance by warning against using webhooks as the sole source of truth and recommending confirmation via GET tools for critical events. It even specifies the limiting condition (up to 5 active webhooks per workspace) and the required owner_key, giving clear prerequisites.

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

All AANet toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources