inkbolt_document_check

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

Annotations already cover readOnlyHint, idempotentHint and destructiveHint=false, so the description's 'Read-only' line is redundant. It does add real behavioral context beyond annotations: bounded diagnostics with repair guidance, checked counts, and an explicit incomplete/skipped status, plus that nested snapshots and overrides are traversed rather than treated as opaque.

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?

Three sentences, each doing work, with the diagnostic scope front-loaded before return shape and the routing hint. The only wasted clause is the redundant 'Read-only', which the annotations already assert.

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 description is not obligated to enumerate return fields, and it nonetheless summarizes them (located diagnostics, counts, incomplete/skipped status). Safety is covered by annotations. Remaining gap is the deferred 'document' schema and the undocumented option/response flags, which the description only partially gestures at.

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 40%, so the description should carry more weight than it does. It obliquely maps to parameters ('nested snapshots and overrides' -> the three document variants, 'pinned resources' -> resources, 'bounded' -> issue_limit), but says nothing about control (timeout_ms/cancel_file), the resources/typography flags, or response_format.

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?

Names a specific verb ('Check') and a precise scope: retained structure, pinned resources, authored text/story overflow, nested snapshots and overrides. That is far more specific than the sibling inspect/query tools, though it never explicitly contrasts itself with inkbolt_document_inspect or inkbolt_document_query, so sibling differentiation is only partial.

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 one routing hint: 'use document.preflight to prepare a specific export.' However, that name does not appear in the sibling tool list (the nearest sibling is inkbolt_document_preview), and there is no stated trigger for when to run a check versus document.inspect/query/render. Usage is implied rather than prescribed.

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