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

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds critical behavioral context: this tool triggers ongoing background work (each run enqueues brand_audit_batch_start), has a per-principal cap of 20 watches, and respects owner scoping. It does not mention whether the response includes the watchId directly (it says 'Returns the new watchId') which is useful but could be inferred from the output schema. The only minor gap is not stating failure modes (e.g., what happens if the cap is hit), but overall this adds substantial value beyond the annotations.

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?

The description is three sentences and 250 characters, fitting all essential information without redundancy. The first sentence nails the core purpose. The second sentence explains the webhook diff and lifecycle, which is a key behavioral detail. The third sentence covers return value and limitations. It could be slightly more structured (e.g., bullet points for the three actions) but is already very clear. Loses a point for minor redundancy in 'each run enqueues a fresh brand_audit_batch_start'—'fresh' is implicit, and 'enqueues' could be more direct like 'triggers'—but overall efficient.

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?

Given the moderate complexity (3 params, output schema present, 20+ sibling tools), the description covers everything needed for correct invocation: what it creates, what parameters matter, the lifecycle (enqueues a run, returns watchId, optional webhook), and constraints (owner-scoped, cap of 20). The presence of an output schema (implied by 'Returns the new watchId' and likely JSON) means the description doesn't need to detail the return shape. No critical gaps remain—the agent can confidently decide when to call this tool vs. list/delete counterparts.

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 100%, so each parameter (domain, interval, webhook_url) is already documented in the schema. The description adds context by mentioning that webhook POSTs happen only when configured and re-validated for SSRF at both registration and delivery time, which goes beyond the schema's description of just 'Optional webhook URL — POSTed on classification drift. Re-validated for SSRF at both register and delivery time.' It also implicitly groups the interval into daily/weekly/monthly, matching the enum. The description does not repeat the schema's details verbatim but integrates them into the workflow narrative, which is a good balance.

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 clearly states it creates a recurring brand-audit watch for a domain with configurable cadence (daily/weekly/monthly). It distinguishes itself from related tools like list_brand_audit_watches (listing) and delete_brand_audit_watch (deletion), and from brand_audit_batch_start (which is a component triggered by this watch, not the watch itself). The verb 'creates' plus the specific resource 'recurring brand-audit watch' leaves no ambiguity.

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 explicitly states 'Owner-scoped; per-principal cap of 20 active watches,' informing the agent of authorization boundaries and a hard limit that may require checking list_brand_audit_watches first. It also notes that each run enqueues a brand_audit_batch_start (explaining the downstream effect) and optionally POSTs a webhook, helping the agent understand when to configure the webhook_url parameter. No alternatives are given because no other tool creates watches, so this is appropriately complete.

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