ass_qc

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

With no annotations, the description carries the burden well: it defines cps precisely (visible chars, tags stripped, breaks excluded, per second), explains that drawing lines are skipped by text checks and reported once as an 'info' with code 'drawing_line', and documents the ok/clean semantics plus issue ordering. It never explicitly states the tool is read-only/no-side-effect, which is the one notable unstated trait.

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?

Front-loaded with the purpose, then a definition block, then per-parameter semantics, then returns. Every section maps to a real decision the caller must make; the prose is dense but slightly repetitive in enumerating all 13 args inline.

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 13-parameter QA tool, the description covers scope, cps computation, special-case handling (drawings), every parameter's trigger condition, and output semantics including ok/clean and sort order. Even though an output schema exists, the clarification of ok vs clean is genuinely additive.

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% across 13 parameters, so the description must compensate entirely — and it does, giving each parameter a meaning and, for thresholds, the exact issue code it triggers (cps_high, cps_extreme, too_short, too_long, too_many_chars, too_many_lines, overlap_same_layer, gap_tiny, empty_text, style_missing, unclosed_override_block, unknown_tag).

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?

States a specific verb+resource: 'QA a selection of lines and return a structured issue report', and the scope (selection or all lines) is defined immediately. It does not name the most likely confusable siblings (ass_validate, ass_check_overlaps, ass_reading_speed, ass_cps), so an agent must infer differentiation from the check list rather than being told.

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?

'selection: lines to check; None/[] means every line' establishes the default scope, and each check_* flag implies when its check runs. However there is no explicit when-to-use-this vs ass_validate or ass_check_overlaps, no statement that this is a non-mutating audit, and no guidance on tuning thresholds for a given workflow.

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