Insert paragraph

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

Goes well beyond the annotations by disclosing tracked-mode w:ins markup, the rejection consequence of removing the whole paragraph, direct-mode ledger accounting, the sibling relationship preserving container boundaries, and the para_hash concurrency guard. This is rich behavioral context the annotations alone do not 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 dense but every sentence contributes needed operational detail: anchor constraints, optional hash semantics, mode consequences, sibling behavior, and commit step. It is front-loaded with the core purpose and then layers the constraints efficiently.

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 9-parameter mutation tool with no schema descriptions, the description covers the essential insertion mechanics thoroughly, but it leaves the required part and author parameters semantically undefined and does not mention note. An agent would still need external knowledge to populate those fields correctly.

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?

With 0% schema description coverage, the description must carry the parameter-semantics burden. It explains text, after_para_id, before_para_id, para_hash, and mode well, but leaves required parameters part and author unexplained, and optional note is also absent. session_id is only implied by the session/journal context, not explicitly defined.

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 operation and resource: insert a new paragraph beside a named existing paragraph and record it in the session's journal. It also differentiates from related tools by explicitly stating there is deliberately no raw index parameter, making the tool's role unmistakable.

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?

Provides clear, actionable guidance: pass exactly one anchor, use para_hash to guard against stale reads, choose tracked or direct mode deliberately, and seal the session with commit_document. It does not explicitly name sibling alternatives or state when not to use this tool, so it falls short of a 5.

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