Check a draft's rhythm against a trained voice

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

Goes beyond the readOnlyHint/idempotentHint annotations by disclosing what the tool returns (verdict, score, drifted dials, caveat), the low-confidence behavior on short input, and a crucial interpretive limitation (not an authorship/AI-detection check). This gives the agent a realistic expectation of outputs and edge cases.

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 detailed but every sentence carries information: comparison semantics, timing, return values, caveat, confidence guidance, and prerequisite condition. It is front-loaded with the first sentence stating the core action, and the rest expands logically.

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 tool has no output schema, the description compensates by explicitly stating what is returned (verdict, match score, drifted dials, caveat, confidence). It also covers the prerequisite about trained/custom voices and the provisional nature of low-confidence results, making the operation fully self-contained.

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 coverage for parameters is 100%, so the schema already explains text, styleId, and id. The description adds contextual meaning by stating the styleId must refer to a trained or custom voice and that bare presets won't work, which is useful but not essential for parameter use.

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: 'Compare a piece of drafted text's measured sentence/paragraph rhythm and mechanics against a trained or custom voice's baseline', and enumerates the measured dials (sentence length, rhythm variance, etc.). This clearly distinguishes it from sibling tools like check_self_repetition, which checks repetition, or audit_text, which audits generally.

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?

Explicitly prescribes when to use it: 'Use this after drafting in a voice to check whether the draft's rhythm actually landed close to it, instead of just eyeballing it.' It also defines an exclusion and a workaround: 'Only works against trained or custom voices... not bare presets... fork_style a preset first if you want to check a draft against one.'

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