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

With readOnlyHint=false, the agent knows this mutates something, and the description usefully adds that a *paid* checkout session is consumed — real billing context beyond the annotations. Beyond that it is silent: it does not say what is produced (repaired SRT text?), whether the session is spent and non-reusable, or whether a failed repair still charges the session.

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?

A single short sentence with the key gating constraint (paid session) up front and no filler. It is efficient, though arguably cut so close to the bone that the parameter and output questions are never addressed.

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 mutating, paid, file-content-in/file-content-out tool with no output schema and low schema coverage, the description should cover what comes back and how billing interacts with failure. It covers only the session prerequisite, leaving the return value and the fate of the paid session unspecified.

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 only 33%: checkout_session_id is documented in the schema, but filename and subtitle_text are not described anywhere. The description's "Repair one SRT" hints that subtitle_text carries the SRT content rather than a path, but the filename-vs-subtitle_text relationship and the 250,000-character cap are left unexplained.

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?

"Repair one SRT" gives a specific verb and resource, and "one" scopes it to a single subtitle file, which separates it by format from repair_csv/repair_ics. It never names diagnose_srt or explains the relationship to it, so differentiation from the sibling that operates on the same format is only inferred from the verb.

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 states a prerequisite (a paid ReadyKit Checkout Session), which is genuinely useful usage context. However, it gives no guidance on when to repair versus when to run diagnose_srt first, and no mention of what to do if the session is unpaid or already consumed.

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