Moltline Humanizer

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

Annotations already set readOnlyHint, idempotentHint, and destructiveHint. The description adds significant value by detailing error handling ('never raises a protocol error — it returns {"error": ...}'), idempotency safety for retries, and the exact response structure. No contradictions with 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 a single well-structured paragraph that front-loads the purpose, follows with a usage example, then usage guidelines, and ends with error behavior. Every sentence adds value; no wasted words.

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?

Despite only one input parameter, the description fully explains the return structure (reads_human_score, metrics, evidence, note) and error handling. The presence of an output schema is supplemented by clear documentation. The tool scope is simple and completely covered.

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?

Only one parameter (text) with 100% schema coverage. The description adds meaning beyond the schema by providing a typical input example ('{"text": "<draft>"}') and clarifying input requirements ('at least one full sentence of plain text'). This aids correct invocation beyond the schema alone.

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 specific verb ('Scan') and resource ('draft') and clearly states the outcome ('measurable tells of AI-generated prose'). It distinguishes from siblings by explicitly naming alternative tools (burstiness_report, humanize_plan) and what those tools cover.

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?

Provides explicit usage context: 'Use for a first read on whether a draft carries machine-writing signals.' Also states when not to use: 'must not be used to accuse a person of anything' and lists alternative tools, satisfying the when/when-not/alternatives criteria.

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

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

The description goes beyond annotations by detailing error behavior: 'on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": ...}' and that it always returns a requested error. It confirms read-only and idempotent behavior beyond the annotations, and explains what results look like. No contradiction with annotations exists.

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 highly concise with 3 short paragraphs, each earning its place. It front-loads the purpose in the first sentence, then delivers a clear example, usage guidance, error handling, and safety guarantees—all in fewer than 100 words. No fluff or repetition.

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's complexity (single parameter, good annotations, provided output schema), the description is complete. It covers purpose, usage, behavior, error handling, and safety. The descriptions and sister names provide clear differentiation from siblings. There is no missing information for an agent to invoke it correctly.

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 is 100%, so the baseline is 3. The description adds value by showing a typical input format with an example and specifying that the text needs at least 3 sentences, which is not fully captured by the schema's description. This additional context justifies a 4, though no detailed parameter metadata is added.

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 the tool's purpose with a specific verb-resource combination: 'Map a draft's sentence rhythm and find where it goes flat.' It immediately distinguishes itself from sibling tools like 'ai_tell_scan' by explicitly naming it as an alternative for a different use case. The example output further solidifies understanding.

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 provides explicit guidance: 'Use when prose reads flat and sentence-length pattern is the suspect. Not for a full inventory of tells (ai_tell_scan).' This tells the agent exactly when to use this tool and when to choose a sibling instead. The retry safety note after error also clarifies correct usage patterns.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds critical behavioral traits: 'never raises a protocol error — it returns {"error": "<what is wrong and how to fix it>"}' and 'Every call is read-only and idempotent, so after correcting the input it is always safe to retry.' This explains error handling and retry safety, which annotations do not cover.

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 dense but not overly long. It is front-loaded with the main purpose in the first sentence. Each subsequent sentence adds useful detail (output fields, usage context, error behavior). There is no fluff, but it could be slightly more concise by combining some ideas. Still, it is well-structured and 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 tool's complexity (nested objects, output schema, premium license), the description covers all necessary aspects: purpose, input, output, error handling, workflow sequence, and sibling relationships. It mentions the typical return format and the integrity_note, which is helpful even though an output schema exists. The description is complete for an agent to use the tool correctly.

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 is 100% with good descriptions for both parameters. The description adds value by explaining the effect of the fingerprint parameter: 'when a voice_fingerprint result is supplied, adds numeric targets to hit that person's voice.' It also provides a concrete example of typical input, which helps the agent understand how to use the parameters together. This goes beyond the schema's static type definitions.

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 the tool's purpose: 'Produce a precise rewrite brief that de-AIs a draft, with numeric targets.' It lists specific outputs (edit_list, numeric_targets) and distinguishes itself from siblings like verify_rewrite and ai_tell_scan, making the tool's unique role obvious.

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 tells when to use the tool: 'Use after a scan has identified what to fix; returns a brief, not rewritten prose.' It also tells when not to use it: 'Not for checking whether a rewrite worked (verify_rewrite).' Additionally, it provides a workflow hint: 'Apply the brief with your agent, then confirm with verify_rewrite.' This is comprehensive guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: the tool never raises a protocol error but returns an error object, and it provides a typical output example. No contradictions.

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 concise and well-structured: a bolded one-line summary, followed by detailed explanation, usage notes, and error handling. Every sentence adds value without redundancy.

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 an output schema, the description adequately covers input format, usage constraints, error behavior, idempotency, and licensing. It also references the sibling tool for single-draft scoring, making the context complete.

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 a baseline of 3. The description adds meaning by showing the typical input format and clarifying that the optional fingerprint is used to 'measure distance to the target voice', which goes beyond the schema's static type description.

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 states the tool 'Verify a rewrite actually improved: score delta, meaning check, voice distance', providing a specific verb and resource. It distinguishes from the sibling ai_tell_scan by explicitly noting this tool is not for scoring a single draft.

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 gives explicit guidance: 'Use only when both the before and the after text are available. Not for scoring a single draft (ai_tell_scan).' It also notes that every call is safe to retry after correcting input, which guides on error recovery.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this explicitly: 'Every call is read-only and idempotent, so after correcting the input it is always safe to retry.' It also discloses error handling behavior ('never raises a protocol error — it returns {"error": ...}') and notes it is free. No contradictions and meaningful additional context.

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 well-structured with a short intro, a detailed example block, and usage guidance. It is slightly long but every sentence adds value. The information is front-loaded with the core purpose and key constraints. Minor redundancy in repeating the 'real writing' constraint could be trimmed, but overall it is efficient for the necessary detail.

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 simple 2-parameter schema, presence of annotations and output schema, the description fully covers all aspects: workflow (input → profile), error behavior, integration with sibling tools, requirements for samples, and idempotency. No gaps remain for an agent to understand how to select and invoke this tool correctly.

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 is 100% with both parameters clearly described. The description adds significant context beyond the schema: example input format ('{"samples": ["<email text>", "<blog post>"]}'), explanation of default label behavior, and details about output fields that help understand how parameters shape the result. This elevates meaning beyond the baseline schema descriptions.

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 'Build a measurable voice profile from samples of a person's real writing.' It identifies the specific verb 'build' and resource 'voice profile' and distinguishes from sibling tools by stating 'Not for scoring an unknown draft (ai_tell_scan)' and references humanize_plan/verify_rewrite. The purpose is explicit and unambiguous.

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 provides explicit when-to-use guidance ('Feed it 2+ samples... use the result with humanize_plan / verify_rewrite') and when-not-to-use ('Not for scoring an unknown draft (ai_tell_scan) and not on text the person did not write'). It also warns about errors and gives retry advice, making it clear when to apply this tool versus alternatives.

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