humanizer_compare

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

No annotations exist, so the description carries the full burden. It usefully discloses the comparison dimensions the tool checks, which is real behavioral context beyond the schema. However it never states that the call is non-mutating/read-only, nor whether it is idempotent or costs anything, which matters for a tool sitting between a rewrite and a save step.

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?

A single tight sentence with the core action front-loaded and the output list compactly enumerated, followed by one short imperative sentence for sequencing. No filler, no restatement of the tool name.

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?

Absent an output schema, the description must explain returns, and it does at the level of categories (scores, remaining tells, preservation checks) but not structure or field names. For a two-parameter read-style comparison this is adequate to call correctly, but thin on what the calling agent should expect back.

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. The pair 'original' and 'rewrite' are named in prose ('Compare an original and a rewrite'), which clarifies role ordering, but the description adds no constraint details such as whether inputs are raw text, size limits, or what happens on identical inputs. Minimal viable given two self-describing required string params.

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?

Names a specific verb (compare) and its two inputs (original, rewrite), then enumerates the concrete outputs: before/after AI-tell score, remaining tells, and survival of numbers, links, emails and quotations. That is far more specific than a tautology. It stops short of differentiating itself from the similarly named sibling humanizer_assess_pair, so an agent must guess which of the two to reach for.

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?

Gives explicit sequencing guidance: 'Call this after rewriting, before saving.' That establishes a clear position in the workflow relative to humanizer_humanize_text/humanizer_save_document. It offers no negative guidance (when not to call it) and no routing against humanizer_assess_pair or humanizer_lint_text, so the when-to-use map is incomplete.

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