ass_stats

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

With no annotations, the description carries the full behavioral burden. It does disclose useful semantics: what average_cps measures (total characters over total dialogue duration), that per-line figures ignore zero-duration lines, and that indices are 0-based. However it says nothing about preconditions (must the document be open?), whether it is a pure read, or how a null doc_id resolves.

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?

Purpose is front-loaded, which is good, but the bulk of the text is a long enumeration of return keys that duplicates the existing output schema. That space would have been better spent on doc_id behavior and usage guidance, so the structure is only adequate.

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?

An output schema exists, so the return-value dump is largely redundant, and the description instead omits the two things an agent actually needs: when to call this versus the other metric tools, and how the optional doc_id resolves. It is minimally usable but leaves clear holes for a 60-plus-sibling toolkit.

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 single parameter doc_id has 0% schema description coverage, and the description never mentions it or explains what happens when it is omitted (default null). With the only parameter undocumented in both places, the description fails to compensate for the coverage gap.

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 opening line 'Statistics for a document' names the resource but uses a noun phrase rather than a specific verb, and it does not differentiate this tool from adjacent siblings such as ass_document_info, ass_cps, ass_reading_speed, or ass_style_usage. The lengthy return-field list does narrow the scope after the fact, but the agent gets no crisp one-line statement of what makes this the right 'stats' tool versus the others.

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?

There is no when-to-use guidance and no mention of alternatives. Given siblings like ass_cps (which likely reports characters-per-second metrics overlapping average_cps/min_line_cps here) and ass_reading_speed, the absence of routing guidance is a real gap. Usage is only inferable from the field names.

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