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

Annotations already declare this is a write (readOnlyHint=false), non-idempotent, and open-world. The description adds genuinely useful context beyond that: the returned signing_secret, the X-AstroWay-Signature HMAC-SHA256 verification scheme, and a 10-credit cost. It stops short of disclosing lifecycle behavior (update vs duplicate subscription, cancellation).

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?

Two tight sentences with the core action front-loaded, followed by compact group/cost tags. Every element is relevant, though the partial event list wastes space by being incomplete rather than illustrative.

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?

An output schema exists (so return structure need not be explained), and the description still usefully surfaces the signing_secret and cost. But for a write/subscription tool it omits usage routing against the many webhook siblings and gives an incomplete event enumeration, leaving real gaps.

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 only 50%, and the description's event list is misleading: it names three events (report-ready, transit-alert, eclipse-alert) while the schema enum allows twelve, so an agent may wrongly assume those are the only valid values. The fields/precision semantics are already documented in the schema, so the description adds little and arguably introduces 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?

States a specific verb and resource ('Subscribe to outbound webhook deliveries') and names the triggering events, so the agent knows this creates a subscription rather than consuming one. However, it never distinguishes itself from the many per-event webhook siblings (e.g. astroway_webhooks_transit_trigger, astroway_webhooks_retrograde_start), which look like overlapping routes to the same events.

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?

There is no when-to-use guidance at all: no prerequisites, no statement of when to prefer this generic subscribe over the event-specific sibling tools, and no note on whether re-subscribing to the same event is expected. The agent must infer usage entirely.

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