humanizer

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses concrete behavior: it never raises a protocol error but returns an error object, it returns a structured response with reads_human_score and evidence, and it is safe to retry after correcting input. This adds substantial context beyond the 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 well-structured with clear sections for purpose, flags, output, errors, and retry behavior. It is slightly verbose, and the 'FREE.' is unnecessary, but each informative sentence earns its place.

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?

The description covers input, output format, error handling, and retry semantics. With annotations and an output schema present, this is a comprehensive description for a single-parameter read-only tool.

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 schema already describes the 'text' parameter with 100% coverage, so the baseline is 3. The description adds a typical input example and explicitly states that the text must be plain text with at least one full sentence, which marginally improves clarity beyond the schema.

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: 'Scan a draft for the measurable tells of AI-generated prose.' It also enumerates specific flags (stock phrases, structural reflexes, uniform sentence rhythm, em-dash overuse, hedging boilerplate), distinguishing it from sibling tools that focus on rewriting or verification.

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 input requirements ('at least one full sentence of plain text') and retry guidance, but it does not explicitly state when to use this tool over the sibling tools (e.g., burstiness_report, humanize_plan). Usage is implied rather than contrasted with alternatives.

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 adds significant context beyond the annotations by disclosing the exact error behavior: invalid input never raises a protocol error but returns an error object. It also reinforces safety by noting every call is read-only and idempotent, making retries safe after correction.

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 front-loaded with purpose and flows logically from output summary to example to error behavior. The only minor point is the one-word 'FREE.' which is not essential for an agent, but the overall structure is 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?

For a simple one-parameter tool with output schema and clear annotations, the description is complete: it defines the input, shows a typical output, explains the error contract, and confirms idempotent retry behavior. Nothing essential 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 schema already covers the text parameter with a clear description and 100% coverage. The tool description reinforces this with a concrete typical input example and an error example requiring 3+ sentences, adding some practical guidance beyond the schema.

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 and resource: 'Map a draft's sentence rhythm and find where it goes flat.' It clearly distinguishes this tool from siblings by focusing on rhythm analysis and reporting burstiness, sentence lengths, and flat runs.

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 intended use case is clear from the phrasing 'Map a draft's sentence rhythm and find where it goes flat,' and it specifies the input needs at least 3 sentences. However, it does not explicitly name alternatives or state when not to use this tool versus the sibling tools.

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 adds error-handling behavior ('never raises a protocol error — it returns {"error": ...}') and outlines the return object structure. While read-only and idempotent are already in annotations, the description provides extra detail on response content and error recovery, going beyond the structured metadata.

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 front-loaded with a clear purpose and follows a logical structure: purpose, behavior, example, errors, safety. It is slightly verbose, repeating annotation info (read-only/idempotent) and including a license note, but each section earns its place.

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?

For a tool with 2 parameters and an output schema, the description covers the input, output shape, error responses, retry safety, and workflow. It lacks an explicit 'when not to use' statement, but given the sibling context and schema richness, it is sufficiently 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 covers both parameters with descriptions, and the description adds the effect of the fingerprint parameter: it 'adds numeric targets to hit that person's voice.' The typical input example further illustrates parameter usage, which is beyond the schema's static 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 opens with a specific verb+resource: 'Produce a precise rewrite brief that de-AIs a draft, with numeric targets.' It clearly distinguishes from siblings by positioning itself as the planning stage ('Apply the brief with your agent, then confirm with verify_rewrite'), making it clear it is not the rewrite or verification tool itself.

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 clear context on when to provide a fingerprint ('when a voice_fingerprint result is supplied, adds numeric targets to hit that person's voice') and suggests a workflow (apply with your agent, then verify with verify_rewrite). It doesn't explicitly list exclusions or alternative tools, but the context implies its role in the pipeline.

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/idempotentHint/destructiveHint, but the description adds valuable context: exact error behavior (returns error object instead of protocol error), safe retry, and the fact that it requires premium license. This goes beyond what annotations provide.

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 rich but well-structured: first sentence gives purpose, then details metrics, typical input/output, error behavior, and safety. Every sentence adds value, with a clear flow from high-level to specifics. Front-loaded purpose and no fluff.

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 moderate complexity, full schema coverage, and output schema presence, the description is complete. It covers purpose, usage, error handling, safety, and even provides example output formats. No critical gaps remain.

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 covers 100% of the parameters with descriptions, so baseline is 3. The description adds extra meaning by showing a typical request/response shape and clarifying that fingerprint is optional and used to measure voice distance, which enriches understanding beyond the schema.

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 verifies a rewrite improved, with a specific verb and resource, and details the main comparison metrics (score delta, meaning check, voice distance). It distinguishes itself from sibling tools like humanize_plan and ai_tell_scan by focusing on before/after verification.

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 describes typical input and output, notes PREMIUM license requirement, and states every call is read-only and idempotent, making retry safe after correcting input. Clear context for when to use this tool (after edits) and no misleading alternatives.

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 adds significant behavioral context beyond annotations: it never raises protocol errors, returns structured error objects, and emphasizes read-only and idempotent behavior making retries safe. This complements the annotations (readOnlyHint, idempotentHint) with concrete error-handling details.

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 front-loaded with a clear main clause, then provides a compact example, error behavior, and safety note. Every sentence adds value; no fluff despite the extra 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?

The tool has only 2 parameters and rich annotations/output schema, yet the description still covers purpose, usage, example, error handling, and safety. It is complete for an agent to select and invoke the tool correctly, with no significant gaps.

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 the baseline is 3. The description provides a typical input example but does not add deeper meaning beyond the schema's parameter descriptions, such as format constraints or nuanced usage tips.

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 and resource: 'Build a measurable voice profile from samples of a person's real writing.' It distinguishes itself from sibling tools by explicitly linking its output to humanize_plan/verify_rewrite and focusing on voice profiling rather than scanning or rewriting.

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: feed 2+ samples totaling 150+ words, and use the result with humanize_plan/verify_rewrite. This implies when to use it (before those tools) but does not explicitly exclude alternatives like ai_tell_scan or burstiness_report, so it lacks full comparative guidance.

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