Register VOC-Start Webhook

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

Adds genuinely useful facts not in annotations: the endpoint path and the 10-credit Tier 1 cost. However, it omits what matters for a non-idempotent registration (duplicate registrations create duplicate webhooks), what payload gets delivered, and whether/how to unsubscribe later.

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?

Very short and front-loaded with the trigger event, then bracketed metadata. The bracketed blocks are slightly noisy but each carries real information (group, endpoint, cost).

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 mutating registration tool with an output schema (so returns need no explanation), the description still fails to say what registration causes: the payload shape delivered to the URL, duplicate-handling behavior given idempotentHint=false, and lifecycle/removal. Missing too much for correct invocation.

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 coverage is 0% and the description only repeats '[Required: url]' which the schema's required array already states. No explanation that url is the receiver endpoint that will be POSTed to, nor the uri format / 2048 char limit.

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?

The description states the event that triggers the webhook ('start of every VOC Moon period'), not the action the tool performs, which the title reveals is registering a webhook. An agent can piece the purpose together from name + title, but the description alone leaves the verb implicit.

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 register this webhook versus polling astroway_calendar_moon_voc or using the streaming sibling astroway_stream_void_of_course. No mention of prerequisites, delivery context, or when not to use it.

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