variety_check

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

No annotations exist, so the description has to carry the full behavioral load, and it does most of the work: it discloses a persistent side effect ("then remembers this opening"), which an agent could otherwise trigger unknowingly, and it names the response shape (`issues` with rule/excerpt/advice, and `ok`). It still leaves open how long an opening is remembered, what "recent" means, and whether that state is shared across callers.

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 lead sentence states the purpose immediately and the detection list is compact and specific rather than padded. The scope sentence is dense to the point of being a run-on, bundling detection, comparison, and state mutation into one clause, but nothing is wasted.

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, yet the description still summarizes the return fields helpfully; the confirmation flag `ok` is especially useful since an agent needs to know pass/fail is signalled separately from the issue list. Given a two-parameter tool with disclosed stateful behavior, the main missing piece is the threshold semantics for subjective checks like "too many exclamation marks".

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 0%, so the description must compensate for both parameters. It explains `scope` well as something broader than a label: it both enables cross-text opening-collision detection and causes the tool to record the opening in that scope. `text` is self-evident as the draft under review. Gaps remain around acceptable scope values and the recency window, so it is not a 5.

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 uses a concrete verb and resource ("Check a draft for common signs of AI writing") and then enumerates exactly which signals are detected (em dashes, stock phrases, "not just X, but Y", uniform sentence length, excess exclamation marks). The scope of the check is unambiguous. It does not differentiate itself from the siblings variety_kinds and variety_pick, so it stops short of a 5.

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?

Usage is only implied: the description says what it checks but not when to run it (before publishing? after drafting?) or why an agent would pick it over variety_pick/variety_kinds. The one conditional that is stated, "With scope, it also flags...", is a parameter behavior rather than an when-to-use rule. No exclusions or prerequisites are given.

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