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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is carried by structured data. The description adds real behavioral context beyond that: the store is immutable, source bytes and existing stored bytes are untouched, alpha and source/profile hashes are retained, and unsupported semantics fail explicitly rather than silently coercing. It does not address permissions, workspace/store defaults, or re-import behavior.

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 and format scope are front-loaded, and every sentence carries distinct information (format scope, color-policy semantics, hash/alpha retention, untagged policy requirement, non-destruction, failure mode). Sentencing is dense and jargon-heavy with phrases like 'declared RGB ICC input profiles', but nothing is redundant.

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 return values need not be explained, and the description covers input formats, color-policy behavior, hash/alpha retention, immutability and failure semantics. Remaining gaps are modest: no statement on whether a re-import overwrites or deduplicates an existing stored asset, and no mention of workspace store defaults for store_root.

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?

Coverage is 60%, so the schema does not fully carry the load. The description supplies the semantics the schema omits: what convert_srgb means for ICC input profiles, that untagged samples force an explicit color_policy choice, and that source/profile hashes and alpha are preserved. store_root and response_format remain undocumented in the description, though their schema descriptions partially cover them.

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?

Specific verb (Read ... into an immutable image store) plus an explicit resource and scope: local PNG/JPEG/TIFF/BMP/TGA/single-frame GIF files. The format enumeration inherently separates it from the sibling inkbolt_font_import, so an agent can route on the description alone.

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?

States the operating condition clearly (explicit local sources, unsupported semantics fail) and gives conditional policy guidance: convert_srgb for embedded/declared ICC input, and an explicit policy required for untagged samples. It stops short of naming when to prefer this tool over an alternative or any exclusion, so it is context without alternatives rather than full routing guidance.

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 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.

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

Annotations already declare readOnly/non-destructive/idempotent, and the description usefully adds that the result is a snapshot and that nothing is written to disk, resolving the tension implied by the verb "Create". It still says nothing about session scope, required permissions, or what the returned snapshot handle enables, keeping it out of 5 territory. No genuine contradiction with annotations, since the tool is explicitly non-persisting.

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?

Two front-loaded sentences with no filler; the create semantics come first and the non-persistence caveat second. It is arguably too terse for a 7-parameter tool, but every sentence earns its place.

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 return values need not be spelled out, but for a 7-param tool with 14% schema coverage the description omits parameter meaning, session/id behavior, and any usage context. It is not complete enough for an agent to call this correctly without opening the schema.

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 14% across 7 parameters, so the description carries most of the burden and does not deliver: it never explains what `id` is (caller-supplied handle? generated?), the pixel units or bounds for width/height, resolution_ppi, or resource_profile. Only the `kind` enum is gestured at via "vector or raster".

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 gives a specific verb and resource ("Create an empty ... document") plus salient attributes (editable, vector/raster, sRGB), so an agent can distinguish it from document_edit, document_render, or document_inspect. It stops short of naming or contrasting any sibling explicitly, which a 5 would require.

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 statement of when to use this tool versus alternatives such as session_create or asset_import, and no preconditions. "Returns a snapshot; does not save a file" describes outcome, not usage context, so the agent is left to infer when a document must be created.

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 declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: atomic batch application, a 1..64 operation bound, lock/resource/full-batch validation, the editable-snapshot-plus-ordered-changes return, and explicitly 'leaves files unchanged.' That last clause is what makes the read-only annotation coherent despite an 'edit' name. Failure/error semantics are the only notable omission.

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?

Five tight sentences, front-loaded with the core action and revision contract, then discovery, then return/validation behavior. Every sentence contributes; there is no filler or throat-clearing.

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?

With an output schema present, the description correctly does not need to enumerate return fields in full, and it still summarizes the return shape and atomicity guarantees. Given the deferred operation schema and 7 parameters, an agent has enough to invoke it, though the when-to-use-this-tool dimension remains thin.

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 57%, so the schema carries much of the load. The description reinforces expected_revision and the 1..64 bound on operations, but it largely repeats the schema's own instruction to call schema.lookup for the operation variant rather than adding new meaning for document, control, or root parameters.

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 gives a specific verb and resource: 'Apply 1..64 typed operations atomically to a snapshot at expected_revision.' That is unambiguous about what happens, and 'Leaves files unchanged' resolves the tension with the read-only annotation. It does not, however, distinguish this tool from close siblings such as inkbolt_session_apply or inkbolt_document_check.

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?

It tells the agent how to proceed internally ('Use add_svg to insert editable SVG fragments', 'discover supported operations with schema.lookup'), which is genuinely useful routing. But it never states when to reach for this tool versus inkbolt_session_apply or inkbolt_document_check, so the sibling-selection guidance is only implied.

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds the concrete scope of inspection (stable IDs, locks, world transforms, unclipped bounds, inventories), which is useful context, but says nothing about cost, pagination, or side effects 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?

A single front-loaded sentence with no filler. It is slightly list-heavy, which reads more like a return-value dump than a purpose statement, but nothing is wasted.

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?

With a full output schema and complete annotations in place, the description does not need to explain return values, and it correctly avoids doing so. It remains thin on the one thing structured data cannot supply: routing guidance against the many inspect/check/query siblings.

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 schema already fully documents both 'document' and 'response_format'. The description contributes no additional parameter meaning, which is acceptable at this coverage level but earns nothing extra.

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 verb 'Inspect' plus a concrete enumeration of what is inspected (item IDs, hierarchy, visibility, locks, transforms, geometry bounds, resource inventories) makes the tool's purpose immediately legible. However, it does nothing to distinguish itself from close siblings like inkbolt_document_check, inkbolt_document_query, or inkbolt_document_inspect_page, so an agent cannot tell from the text alone which of these to pick.

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 statement, no prerequisites, and no mention of alternatives, despite four sibling tools operating on the same document concept. The agent must infer the usage context entirely from the name and output list.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real value beyond them: the cursor 'binds exact document content, view and page limit' (a snapshot-consistency guarantee), and hidden/locked items are included while resources are structural inventories. It does not describe error or empty-page behavior, but for an annotated read tool this is solid.

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 tight sentences with the core purpose front-loaded and no filler. Slightly dense, but every clause carries distinct information (paging, cursor binding, inventory semantics, pinned references).

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 return values need no explanation, and the description covers paging and resource semantics. However, given the complex multi-variant View2 union and the three-way document input, the description leaves the agent to infer how this tool relates to its many document_* and session_* siblings. Adequate minimum, not complete.

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 50%, so the schema already documents part of the surface. The description usefully maps the view argument to its three collection variants (item fields, asset/font inventories, path anchors) and explains that the cursor binds content/view/limit. It adds nothing for control or response_format, leaving the params-without-descriptions uncompensated.

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: 'Read bounded pages of selected item fields, asset/font inventories or path anchors.' The 'bounded pages' framing distinguishes it from the non-paged inkbolt_document_inspect sibling, though it never names that sibling explicitly, so the pagination-vs-single-read distinction is implied rather than stated.

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?

'Use pinned saved references to avoid resending documents' gives one clear usage tip, but there is no guidance on when to prefer this over inkbolt_document_query, inkbolt_document_check, or the unpaged inkbolt_document_inspect. Usage is implied by the paging framing rather than specified.

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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: the call returns explicit world/pixel matrices and exact document identity, and region/object views crop the full composition rather than re-rendering a subset. It stops short of covering cost, size limits, or the deferred document-schema prerequisite.

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, all load-bearing, with the core capability front-loaded and the response_format hint placed last where it belongs. It is appropriately sized for the tool's complexity, though the second and third sentences are dense enough to require re-reading.

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 return-shape explanation is not required. Against a 6-parameter tool with nested options and a deferred document schema (resolved via inkbolt_schema_lookup), the description is adequate on the rendering story but silent on the snapshot/revision input requirement and on how preview differs from render — the two gaps an agent is most likely to hit.

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 67%, so the schema already documents several parameters (response_format, bounds, margin, roots). The description's enumeration of 'canvas, document region, selected objects or standalone artboard' mirrors the `focus` union, and the cropping note adds semantic meaning to region/object focus. It adds little for scale, max_size, render_options, or control.

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 specific verb+resource combination — render a canvas, region, selected objects, or artboard as PNG — and enumerates the four view targets, which maps cleanly onto the `focus` union in the schema. However, it never differentiates this tool from the obvious sibling `inkbolt_document_render`; the phrase 'preserving render semantics and limits' hints at a relationship without resolving which tool an agent should pick.

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 only usage instruction is 'Use response_format structured or preview for summary text,' which is a parameter choice, not guidance on when this tool applies versus `inkbolt_document_render` or `inkbolt_document_inspect`. There is no statement of prerequisites, exclusions, or the conditions under which a preview is the right call.

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 declare read-only, idempotent, non-destructive, closed-world semantics, so the safety bar is low. The description adds real value beyond that: default visibility/lock filtering ('visible, unlocked items') and the crucial constraint that 'Returned command indices address this document revision,' warning the agent that indices are revision-scoped.

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 tight clauses lead with the primary capability, then add the optional anchor behavior and the default/revision caveats. Every sentence carries load. Slightly dense with specialized vocabulary, but nothing is wasted.

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 return format need not be described. The description covers defaults, coordinate frames, and revision-scoped indices, which is strong for a query tool with nested filter semantics. The main gap is sibling differentiation and the meaning of response_format.

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 67%, and the description compensates by mapping prose to parameters: 'content type' (types), 'shape' (shapes), 'inclusive geometry bounds' (region), 'visible, unlocked items' (visible_only/include_locked), and 'path anchors in local/world coordinates' (include_anchors). Only response_format and anchor_bounds semantics are unexplained, but the added meaning over the raw schema is substantial.

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: 'Discover editable item IDs by content type, shape and inclusive geometry bounds.' An agent understands this is a filtered query over document items. However, it never distinguishes itself from siblings like inkbolt_document_inspect or inkbolt_document_inspect_page, which likely overlap in intent.

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?

No when-to-use, when-not-to-use, or alternative is stated. The description doesn't tell the agent whether to reach for this instead of document_inspect or document_inspect_page when hunting for item IDs. Conditions for using anchors vs region are also left implicit.

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 declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds the output pixel format and the resource-root dependency rule, but says nothing about size bounds of a 'bounded snapshot', timeout/cancellation behaviour, or cost/limits.

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?

Two compact sentences with the core action front-loaded and no filler. The second sentence is conditional guidance rather than padding, though 'bounded' is left undefined.

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?

With an output schema present, return values need not be explained, and annotations cover safety. Still, for a 7-parameter render tool the description omits what 'bounded' means, whether output is returned inline or as a reference, and how it differs from the preview sibling.

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 57% and the schema itself carries long normative text for document, session_root, cancel_file, asset_root and font_root. The description only restates the asset_root/font_root condition, adding no syntax, format or default that the schema does not already provide.

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 gives a specific verb (Render), a specific input (a bounded snapshot) and a precise output format (straight RGBA8 hex pixels), which is more than a tautology. It does not however name or contrast with the obvious siblings such as inkbolt_document_preview or inkbolt_document_inspect_page, so an agent must still infer where this fits.

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 statement of when to choose this tool over inkbolt_document_preview, inkbolt_run, or the inspect variants. The only conditional ('Supply asset_root and font_root when stored resources are referenced') is parameter-level advice, not usage routing or exclusions.

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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds real context beyond them: the source is a local file, copies are published as immutable bytes plus license, and a pinned descriptor is returned. It aligns with the idempotent hint via 'immutable' and does not contradict. Permission/error behavior is still unstated.

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?

Two front-loaded sentences with no filler; the read/publish/return sequence is ordered and each clause carries distinct information.

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 return values need not be explained, and schema coverage is high. However, for a write-to-store tool the absence of any usage/routing guidance and any note on the 'permitted' permission requirement leaves meaningful gaps.

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 80%, so the baseline is 3. The description loosely maps to source_path/license_path ('local outline font', 'UTF-8 license') and store_root ('explicit store'), but adds no format, syntax, or default details beyond the schema.

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 specific verbs (read, publish) and resources (local outline font, UTF-8 license, store, pinned descriptor), which is well beyond a tautology. It does not explicitly name a sibling to differentiate from (e.g. inkbolt_asset_import), so it stops short of a 5.

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 word 'permitted' hints at a prerequisite, but there is no explicit when-to-use, when-not-to-use, or alternative tool guidance. An agent gets no routing help against the large sibling set (asset_import, session_*, document_*).

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?

Adds context beyond annotations: revision checks on edits, durable retry receipts, and that source files/existing outputs are preserved. That retry and revision semantics are genuinely new information. The claim that outputs are preserved sits in mild tension with destructiveHint=true, but the command enum plainly mixes read and mutating operations, so this reads as scoping rather than contradiction.

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?

Four tight sentences, front-loaded with the core action and immediately followed by the discovery prerequisite. Little waste; the preservation/retry sentence is the least essential but still informative.

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?

Has an output schema, so return values need no explanation, and delegation to schema_lookup is a sound pattern for a mega-dispatcher. But the description does not convey that individual commands vary widely in destructiveness or prerequisite state, which an agent selecting among 100+ commands would benefit from knowing.

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 schema's 'arguments' object is only partially described (33% coverage), and the description compensates by clarifying that arguments come from schema.lookup and must omit command, which mirrors the schema's own note. For a free-form pass-through object keyed to 100+ enumerated commands, this is adequate but no more.

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 (run engine commands) through 'the same validated executor', and names inkbolt_schema_lookup as the discovery route, which separates it from the many inkbolt_* per-operation siblings. It's a catch-all dispatcher so the description can't enumerate what it covers, but the role is unambiguous.

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?

Tells the agent to discover command names and arguments via inkbolt_schema_lookup, which is useful routing guidance. However, it never explains when to use inkbolt_run versus the many specific siblings (inkbolt_document_edit, inkbolt_session_apply, inkbolt_asset_import, etc.) that appear to wrap individual commands, leaving the main selection decision to inference.

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 declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description redundantly echoes 'Read-only.' It does add useful context about outline budgeting and that the original schema command returns the entire engine schema, but this is modest additional disclosure beyond the annotated safety profile.

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 core verb and resource, then efficient procedural sentences. Slightly dense but each sentence carries actionable routing information without padding.

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?

With an output schema present, return shapes need not be explained, and the description covers the discovery workflow, outline behavior, and full-schema escape hatch. Missing only explicit when-not-to-use guidance, but overall sufficient for correct invocation.

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%, so the schema documents all four parameters including the full, name, select, and response_format with defaults and enum. The description reinforces the intended workflow (name index discovery, variant selection, full:true) but adds no syntax or format detail beyond what the schema provides. Baseline 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?

States a specific verb (lookup/discover) and resource (command arguments and shared graphics types), which distinguishes it from write-oriented siblings like inkbolt_run. It does not explicitly name a sibling alternative, keeping it short of a 5.

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 clear procedural guidance: use name index to discover names, select a variant/definition or use full:true for all reachable definitions. It explains the outline-vs-full tradeoff, though it frames this as mechanics rather than when to choose this tool over alternatives.

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 flag destructive=true, idempotent=true, readOnly=false, so the safety profile is partly covered. The description adds meaningful context beyond the boolean: the retry-identity mechanism ('same-payload retries return the original receipt without reapplying') and the optimistic-concurrency requirement. It stops short of explaining what state undo/restore/remove_snapshot actually destroy.

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?

Two tightly written sentences with the purpose front-loaded and the requirements/retry behavior trailing. No filler, though the action enumeration could be slightly condensed.

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 return values need not be described, and annotations carry the safety profile. Combined with the stated mutation semantics and retry guarantees, the definition is largely sufficient for a complex commit tool; the main gap is routing versus sibling session tools.

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 low (38%) across 8 parameters, so the description should compensate. It names expected_revision and request_id but does not explain their semantics (e.g., that the revision guards against stale writes or what 'unique' means for retries), leaving most parameters to the schema.

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 ('Commit') and enumerates the exact action variants (atomic edit, undo/redo, snapshot action, resource-binding change), which maps cleanly onto the schema's oneOf Action. It does not, however, differentiate itself from close siblings like inkbolt_session_apply_proposal or inkbolt_session_dry_run, so an agent must infer the distinction.

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 preconditions ('Requires expected_revision and a unique request_id') but no guidance on when to use this versus the adjacent proposal/dry-run/diff tools, and no explicit exclusions. Usage is only implied by the word 'Commit'.

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?

Goes beyond the annotations by disclosing the conditional commit semantics and that atomic history, resource checks and durable retry receipts are preserved, plus the assurance that no source or output is overwritten. This meaningfully qualifies the destructiveHint=true and idempotentHint=true flags with what actually gets protected.

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?

Two dense sentences with the verb and the guard condition front-loaded, followed by the preserved invariants. Every clause carries information and nothing is restated from the schema.

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?

With an output schema present and annotations covering the safety profile, the description only needs to explain the conditional commit and invariants, which it does. The main remaining gap is that it does not explicitly distinguish this tool's role from inkbolt_session_apply.

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 50% and the description maps its matching semantics onto the proposal fields (revision, action, before/after content), which adds real meaning for expected_revision and the state hashes. It says nothing about control, session_root, response_mode or response_format, so baseline 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?

States a specific verb (commit) and resource (reviewed dry-run proposal) plus the guard condition (revision, action, before/after content must still match). This differentiates it from the sibling inkbolt_session_apply, which takes an action directly rather than a proposal. It stops short of naming that sibling explicitly, so it falls just under a 5.

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 phrase 'reviewed dry-run proposal' implies the workflow (dry_run first, then apply_proposal) and the compare-before-commit condition tells the agent when the call will succeed. However, no alternative tool is named and no explicit when-not-to-use guidance is given, leaving routing to inference.

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 declare idempotentHint=true and destructiveHint=false, so the retry advice is partly redundant. The description still adds real behavioral facts beyond the annotations: that session revision starts at zero and that the tool 'Never overwrites another session', which is important collision semantics an agent cannot infer from the structured fields.

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 short sentences, front-loaded with the core action, then the revision-zero fact, then the retry and overwrite guarantees. No filler and nothing buried.

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 return values need not be described, and the annotations plus description cover safety semantics. But the document parameter is a deferred schema requiring inkbolt_schema_lookup and offering three variants (inline snapshot, saved revision, pinned file); the description never surfaces that fork, leaving the agent to discover it in the schema.

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 only 50% across 8 parameters, so the description would need to compensate, but it only loosely maps 'snapshot' to the document union and 'resource roots' to resources. It adds no meaning for session_id or session_root; however, the schema itself carries detailed descriptions for document, response_mode, and response_format, so a 3 reflects the schema doing most of the work.

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 ('Create a durable local editing session from a snapshot and resource roots') and clarifies the resulting state ('Starts session revision zero'). It is distinguishable from siblings like inkbolt_session_apply or inkbolt_session_publish, though it never names an alternative explicitly.

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 one concrete operational rule ('use the same request_id for safe retries') but no when-to-use vs alternatives guidance — e.g. that this must precede inkbolt_session_apply, or how it relates to inkbolt_document_create. Usage is implied by the lifecycle rather than stated.

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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuine behavioral context the annotations do not: rendering uses immutable captured states and the database read lock is released first, implying concurrent reads are safe. It does not mention the cost or effect of compare_pixels.

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?

Two front-loaded sentences with no filler; the core operation is stated first. The second sentence is terse to the point of being cryptic about a lock, but nothing is wasted.

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 7-parameter tool with 29% schema coverage and a preview sibling, the description is too thin: it omits usage routing, revision-range semantics, and the pixel-comparison option. An output schema exists, so return values need not be explained, but the input-side gaps remain substantial.

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 29% across 7 parameters, so the description must compensate and largely does not. session_id, from_revision, to_revision and especially compare_pixels (a non-obvious pixel-diff flag defaulting to false) carry no explanation in either the schema or the description.

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: 'Compare two committed session revisions', and adds scope ('including saved resource bindings'). The word 'committed' implicitly distinguishes it from inkbolt_session_diff_preview, but that sibling is never named, so the differentiation is left to inference.

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 explicit when-to-use guidance. The 'committed' qualifier hints that preview/working-tree revisions belong to inkbolt_session_diff_preview, but the agent must infer this — no alternative is named and no prerequisite (e.g. needing two existing revisions) is stated.

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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description goes beyond that with real behavioral facts: outputs use a common sRGB display view, output ICC profiles are recorded but not applied, and fractional grid shifts are rejected rather than resampled. These are exactly the non-obvious constraints an agent needs.

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, no filler, and the artifact list is front-loaded before the behavioral caveats. It is dense to the point of being slightly packed, but every clause carries information and nothing is repeated from the schema or annotations.

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 return values need no explanation, and annotations carry the safety profile. Given a fairly complex tool with nested focus options and 7 parameters, the description covers the sophisticated semantics (ICC handling, grid-shift rejection, focus modes) well; only the basic session/revision parameters and response_format are left implicit, which is a minor gap.

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 29%, so the description does carry weight: it enumerates the focus variants (canvas, region, union-of-items, standalone artboard) and explains the thresholded delta concept. But it says nothing about session_id, from_revision, to_revision, response_format, or the control/timeout parameters, leaving a third of the surface undocumented in both places.

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 names a specific verb (review) and resource (immutable revisions) and enumerates the concrete artifacts produced (aligned before/after PNGs, change mask, RGBA8 deltas, source hashes, structural diffs, coordinate maps). An agent can tell exactly what it gets back. However, it never names or contrasts with the very close sibling inkbolt_session_diff, so differentiation is implied rather than stated.

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 lists capabilities (canvas/region/items/artboard focus) but gives no when-to-use guidance, no conditions that select this over inkbolt_session_diff or inkbolt_session_apply, and no exclusions. A single clause ('session form captures both saved revisions in one transaction') gestures at scope but stops short of routing guidance.

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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: it returns a content-bound proposal, predicted receipt, structural differences, and optional PNG/pixel comparison, which tells the agent what a dry run produces even though an output schema exists.

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?

Two tight sentences, front-loaded with the core purpose and the non-mutation guarantee, followed by the return payload and the commit pointer. Every clause carries information and nothing is wasted.

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 complex 8-parameter tool with a deferred action schema (variant resolved via schema.lookup), the description covers purpose, output shape and workflow but leaves concurrency/optimistic-locking semantics (expected_revision) and the action variants unexplained. Adequate as a minimum, but not fully proportioned to the tool's complexity.

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 25%, so the description must compensate for undocumented parameters, but it does not. It hints at options.preview/compare_pixels via 'optional PNG/pixel comparison', yet the required expected_revision, session_id, request_id and the multi-variant action union receive no explanation in the description.

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 ('Evaluate any session action on the expected head') plus the crucial differentiating property ('without changing the database'). It also names the sibling that performs the real commit (session.apply_proposal), so an agent can distinguish dry-run from apply without opening either 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?

Explicitly frames the preview-then-commit workflow ('Use session.apply_proposal with the same action to commit after review'), which is real when-to-use guidance pointing at an alternative. It stops short of covering the broader sibling set (session_apply, session_diff, run) or stating when a dry run is unnecessary.

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 declare readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description does add real value the schema lacks by capping limit at 128 (the schema only sets minimum 0, no maximum) and describing the pagination cursor protocol, but it says nothing about result volume, ordering ties, or errors.

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?

Two sentences, no filler, with the core scoping verb and ordering stated first and the paging recipe second. Slightly abstract phrasing ('receipts', 'revision order') keeps it from a 5, but it is efficiently front-loaded.

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?

With an output schema present, the description needn't explain return values, and it correctly references next_after_revision as an output-side cursor. Pagination and limit bounds are covered; only the identity/root parameters and any ordering or failure behavior are left unaddressed.

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 40% (only session_root and response_format carry descriptions), so the description must compensate. It clarifies limit's practical range and after_revision's role as the continuation cursor, but session_id and session_root receive no mention in the description.

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 ('Page') plus resource ('committed history receipts') and ordering ('revision order'), which separates it from the singular inkbolt_session_receipt and from inkbolt_session_read. It does not explicitly name a sibling as the alternative, so it falls short of a 5.

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?

It gives concrete mechanics for iterating pages (limit range, pass the previous next_after_revision as after_revision), which implies when to use it for paginated browsing. However, it never says when to prefer this over inkbolt_session_read, inkbolt_session_receipt, or inkbolt_session_diff, leaving that choice to inference.

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?

Adds substantial behavior beyond the annotations: create-only semantics, no undo step, exact-head revision checks, receipt retry returning the original result even after the session advances/disappears, and a Windows-only durable backend constraint. It aligns with idempotentHint=true and destructiveHint=false; only the lack of auth/permission context keeps it from a 5.

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?

Four sentences, front-loaded with the core publish action, then the receipt recovery semantics, then the platform caveat. Dense technical vocabulary but no wasted 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?

An output schema exists, so return values need not be documented here, and the description covers the distinctive write/retry/platform behavior well. Minor incompleteness on the report/output parameter shape is largely handled by the schema.

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 43%, so the description should carry more weight. It clarifies receipt:{receipt_root,request_id} and the expected-revision capture, which adds real meaning, but leaves output, control, session_id, and session_root unaddressed, so the coverage gap is only partly compensated.

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: 'publish its document or artboard create-only without adding an undo step.' This is clear and somewhat differentiating from siblings like inkbolt_session_apply, though it does not explicitly name an alternative. An agent can tell it publishes prepared output rather than editing the session.

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 explicit guidance on when to choose this over inkbolt_session_apply, inkbolt_session_apply_proposal, or inkbolt_session_dry_run. The receipt sentence describes a conditional behavior but not the overall when-to-use decision, leaving routing to inference.

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 declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered without the description. The description adds useful content scope (document, resource roots, revision, history depths) but says nothing about authorization needs, size/cost of the full response, or side effects of reading a snapshot.

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 front-loaded sentence with the action and scope stated first and the returned content trailing. No filler or redundancy, though the trailing enumeration is dense enough that a 5 is not warranted.

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?

With an output schema present, return values need no explanation, and annotations cover the safety profile, so the remaining burden is routing and parameter guidance. The description leaves the agent without any signal for choosing this tool over session_history, session_diff or session_receipt, which is a real gap in a 21-tool family.

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 60%: session_root, response_mode and response_format already carry detailed schema descriptions, and the description's mention of 'a named snapshot' only lightly maps to the undocumented snapshot parameter. The required session_id has no description in either the schema or the description, so the prose does not compensate where coverage is missing.

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 gives a specific verb ('Read') and resource ('the current session or a named snapshot') and enumerates what the payload includes (document, resource roots, current revision, history depths). It is clear, but it never distinguishes this tool from siblings like inkbolt_session_history, inkbolt_session_diff or inkbolt_session_receipt, which also surface session state.

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 explicit when-to-use guidance and no alternative tool is named, despite ~20 session/document siblings. The only implicit signal is the current-session vs named-snapshot branch, which does not tell an agent when this read is preferable to session_history or session_diff.

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 cover read-only, idempotent, non-destructive, closed-world. The description adds real context beyond them: the returned document/receipt is the original committed historical result, distinct from current head fields — critical for interpreting output. It does not mention behavior when request_id is unknown or how the retry identity ties to session_id.

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?

Two tight sentences, front-loaded with the action and keyed on request_id; the second sentence earns its place by disambiguating the historical result from current head. No filler or restated boilerplate.

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 return values need no explanation, and annotations carry the safety profile. Given a recovery-oriented tool with 5 params, the description covers the essential scenario and output caveat; only the missing sibling routing and not-found behavior keep it from a 5.

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 60% and the schema itself details session_root, response_mode and response_format. The description only echoes request_id ('by request_id') and adds nothing about the compact/full tradeoff or the format enum. Baseline 3 is appropriate since the schema carries most parameter meaning.

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: 'Recover the original committed document and receipt by request_id.' The qualifier 'Current head fields are separate from the historical result' usefully pins down that this returns a historical snapshot rather than the current state, but no sibling tool is named for contrast.

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?

'after a lost response' gives a concrete trigger condition, which is more than the usual implied usage. However, it never names an alternative (session_history, session_read, session_diff) or states when NOT to use this tool, so the agent must infer routing from the siblings themselves.

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