Ebook File Check

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

Annotations already carry readOnlyHint=true, openWorldHint=true, destructiveHint=false, and the description adds substantial context beyond them: pinned engine version, offline sandbox, live download with a 110-second deadline plus an explicit instruction to 'tell the user before the call', and what a pass does not certify. No contradiction with 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?

Densely written and front-loaded with the core action before any detail. However, the long enumeration of return fields (pass boolean, severity counts, rule ids, structural inventory, SHA-256) is largely redundant given that an output schema exists, per the rubric that description needn't explain return values when one is present.

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 3 parameters including a nested file object, an output schema, and significant operational constraints (mutual exclusivity, 110-second deadline, sandbox, live download), nothing an agent needs to invoke it correctly is missing — constraints, caveats, and pre-call user notification are all present.

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 schema already documents url/file mutual exclusivity ('never both', STRICT RULE text) and maxMessages bounds, so the description's restatement of the one-source rule adds little beyond what the schema provides.

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 and resource — 'Validates one EPUB ... against the EPUB 2/3 specification' — with precise context (EPUBCheck 5.4.0, no-network sandbox). The 'one EPUB' framing and single-source rule clearly distinguish it from the sibling ebook_compare without opening any schema.

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?

Gives explicit when-to-use signals with three concrete example intents: 'is this ebook valid', 'does this EPUB have specification problems before upload', 'what is wrong with it'. It also states hard limits — pass 'never renders the book, judges accessibility, or guarantees any store will accept it' — but never names ebook_compare as the alternative routing, so sibling differentiation is implicit rather than explicit.

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 mark the tool read-only and non-destructive, but the description adds vital behavioral context: one shared 110-second deadline, sequential execution, tie behavior with no winner, title-mismatch flagging, and the explicit warning that ranking reflects conformance only, not rendering quality. This goes well 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 long but dense: every clause adds a needed constraint, caveat, or instruction, from the sequential 110-second deadline to the tie-handling rule and the requirement to warn the user before calling. The core operation is front-loaded, and there is no filler.

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 source types and ordering, output fields, ranking semantics, tie behavior, title-mismatch detection, human-review requirements, and expected duration. With an output schema and annotations available, nothing essential to calling the tool correctly 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?

Schema coverage is 100%, and the schema already documents urls, files, and maxMessages thoroughly. The description reinforces baseline/revised ordering and source modes but does not add meaningful semantics for maxMessages, so the baseline score of 3 is appropriate.

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 precise operation: running the same pinned EPUBCheck 5.4.0 validation over exactly two EPUB builds and reporting regressions/fixes. It clearly differentiates the comparison purpose from a single-build check and names the concrete questions it answers.

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 explicit use cases ('did my re-export get worse', 'which build has fewer problems', revision-over-revision questions) and specifies baseline-first, revised-second ordering. It does not explicitly tell the agent when NOT to use it or to use ebook_check for single builds, so it lacks a formal alternative/exclusion statement.

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