growsurf_test_campaign_webhook

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

Annotations are sparse (destructiveHint=true, openWorldHint=true) but the description adds meaningful context on top: it discloses that a live event goes to an external endpoint using stored credentials, that it returns both the mock payload and the endpoint's response, and the 400 error edge case for webhooks with no enabled events. No contradiction with annotations — the side-effecting 'send live' behavior aligns with destructiveHint=true. Could have noted that delivery is a genuine external call, but the 400 and response detail already carry the burden.

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?

Four tight sentences, all substantive: core action first, then event semantics, then return value, then campaign targeting. The most important scoping constraint (default event, 400 case) is front-loaded. No filler or repetition of schema-only content; each sentence earns its place.

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 moderate-complexity tool (3 params, 1 enum, open-world campaign default, error cases), the description is largely complete: it covers purpose, param behavior, return value, and the notable failure mode. Since an output schema exists, the return description is a bonus rather than required. Minor residual gaps — e.g., behavior when webhookId is invalid or network errors on the endpoint — are not covered, but the essentials are present.

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 only 33% (only campaignId is documented in the schema), so the description must compensate. It does: it explains `event`'s defaulting and error behavior, clarifies campaignId's GROWSURF_CAMPAIGN_ID fallback, and implies webhookId's role via 'webhook on your GrowSurf program using its stored URL and secret.' Only minor gap is that webhookId itself is never named as the target identifier, but the enum for `event` and campaignId guidance give agents enough to call it correctly.

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 opens with a specific verb-resource pair — 'send a live test event to a webhook' — and clarifies it uses 'its stored URL and secret.' This clearly distinguishes it from sibling webhook tools (create/update/delete/list) since it is the testing action, and the purpose is unambiguous even before reading the schema.

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?

The description explains behavioral outcomes well (default event selection, 400 on no enabled events, campaignId fallback) but never says when to reach for this tool versus alternatives like growsurf_create_campaign_webhook or growsurf_webhook_normalize. Usage context is implied by 'test' in the name rather than stated, and no exclusions or 'use X instead' guidance is offered.

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