inkbolt_session_create

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.