check_punctuation

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that pairs with missing glyphs are skipped, all masters are analyzed when master_id is omitted, and that glyph colors are not modified unless mark_glyphs=True, with specific color verdicts. This is transparent about side effects and defaults.

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: purpose is front-loaded, checks are organized into clear bullet lists, and an Args section closes it out. The length is justified by the detailed check criteria, but it is slightly long relative to simpler tools.

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 is complete for a read-only check tool: it covers defaults, side effects, the missing-glyph edge case, and parameter semantics. An output schema exists, so explaining return values is unnecessary.

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?

Since schema description coverage is 0%, the description must compensate, and it does thoroughly. It explains that master_id is optional with an empty value meaning all masters, and that mark_glyphs only colors glyphs when explicitly requested. This adds significant meaning beyond the schema's type and default declarations.

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 a specific verb ('Check') and resource ('punctuation consistency'), and then details the exact checks performed: mirrored pairs, width matches, and ratio checks. This clearly delineates it from sibling analysis tools like check_compatibility or check_overshoots by focusing on a distinct domain.

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 offers no guidance on when to use this tool compared to its siblings. The only usage-related note is the default behavior for master_id, but there is no mention of alternatives, exclusions, or conditions that would make this tool preferable.

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