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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavior beyond them: the additive (never replacing) semantics relative to jt_watch_list, the 50-rule cap, retroactive matching of tails registered after rule creation, and the auth requirement (account OAuth/key, not a system key). Those are exactly the operational facts an agent cannot infer from 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?

One dense but well-ordered sentence that front-loads the core definition, then layers scope distinctions, cardinality limit, and auth prerequisite. Every clause carries information an agent would otherwise have to guess.

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?

With an output schema present (so return values need no explanation), zero parameters, and annotations covering safety, the description supplies the remaining essentials: what a rule matches, the 50-rule ceiling, the additive relationship to the explicit watch list, and the required credential type. Nothing needed to call it correctly is missing.

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?

The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate — the baseline of 4 applies. The description correctly implies the account scope comes from the connection rather than an argument.

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 ('rules this account uses to watch aircraft BY PROFILE') and immediately enumerates the profile dimensions (model family, owner state, category, RBAC classification). It explicitly contrasts the scope with 'one registration at a time', which cleanly separates it from the sibling jt_watch_list.

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?

Explains that this complements rather than replaces jt_watch_list ('Adds to (never replaces) the explicit list from jt_watch_list'), which is exactly the routing information an agent needs. It also states the connection prerequisite. It stops short of saying when the tool should not be used or pointing to jt_watch_rule_add for rule creation.

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