Insert Break

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

Annotations declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is partially known. The description adds substantial behavioral context beyond that: auto-backup to prev/anchor slots in .ks4w-backups, backup=False only skips rotation, atomic validated save, and refusal to operate on documents open in Word. This is exactly the kind of mutating-tool behavior an agent needs to know.

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 dense sentences carry distinct, non-overlapping information: the core action, the type enumeration, the location semantics, and the safety/failure behavior. The definition is front-loaded with the verb+resource and contains no filler or repeated concepts.

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 4 parameters, 0% schema coverage, and an output schema present, the description covers all critical aspects: purpose, type semantics, location, backup behavior, atomic validated save, and the Word-lock refusal. The only minor undefined term is 'located paragraph,' but the description handles this by providing a default behavior (document end), making the tool sufficiently complete 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 description coverage is 0%, so the description itself must explain the parameters. It fully describes type (page vs section_* and their formatting implications), location (picks the paragraph, omitted for document end), and backup (backup=False only skips rotation; auto-backup is default). file_path is implied by the required field and the document context. No parameter is left unexplained.

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 opens with a specific verb+resource pair: 'Insert a break after the located paragraph,' which clearly states the operation. It then enumerates the type variants (page vs section_*) and introduces the location concept, making the tool unmistakably distinct from sibling insert_paragraphs or delete_paragraphs. The name and title align with the described behavior.

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 provides clear directional context: it explains the effect of each type option, states that location can be omitted to target the document end, and warns that documents open in Word are refused. It does not explicitly name an alternative tool for inserting normal paragraphs, so it lacks an explicit when-not statement, but the usage context is otherwise unambiguous.

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