KitchenSink4Word

Overview Schema Source Related Servers Discussions Admin

Set Paragraph Text

set_paragraph_text

DestructiveIdempotent

Replace a specific paragraph's text in a Word document, preserving its style and formatting. Use a location object to target the paragraph, with optional 'expect' check to avoid wrong edits.

Instructions

Replace one paragraph's full text, keeping style and base formatting; address it with a location object ({paragraph: N}, {search: ...}, {outline: ...}). Indices shift after edits, so pass expect (a substring the target must contain) to refuse instead of hitting the wrong paragraph; verify the returned replaced_text. Auto-backup in file mode (backup=False skips rotation); atomic validated save. Edits go live on open documents (serialized); tracked-revision paragraphs refuse live. For batches, use apply_edits.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`live`	No	auto: file or live; force: live; off: refuse	auto
`backup`	No
`expect`	No
`location`	Yes
`new_text`	Yes
`file_path`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.2.1Sep 24, 2026
- addedInput schema / properties / live / description
```
Added value: +"auto: file or live; force: live; off: refuse"
```
- addedInput schema / properties / live / enum
```
Added value: +[
+  "auto",
+  "force",
+  "off"
+]
```
Addedv2.0.0Sep 4, 2026

TDQS

A5/5.0

Behavior5/5

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

Beyond the destructiveHint and idempotentHint annotations, the description discloses meaningful behavior: index shifting after edits, the expect guard to avoid wrong-paragraph hits, auto-backup behavior, atomic validated saves, and serialized live edits on open documents. No contradiction with annotations was found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence earns its place: main operation, addressing strategy, safety guard, backup behavior, live-editing caveat, and batch alternative. It is front-loaded with the core action and avoids filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description covers the essential operational concerns: how to locate the paragraph, how to avoid index-shift mistakes, what to verify, backup semantics, live behavior, and tracked-revision refusal. With an output schema present, return-value details need not be duplicated here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at only 17%, the description compensates strongly: it defines the location object forms ({paragraph: N}, {search: ...}, {outline: ...}), explains expect as a safety substring, and clarifies backup=False skips rotation. This adds real meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: "Replace one paragraph's full text." It further clarifies scope by noting that style and base formatting are preserved, which distinguishes it from formatting-focused siblings like set_paragraph_format and batch-oriented apply_edits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly names the alternative for batches: "For batches, use apply_edits." It also gives practical usage context: how to address the paragraph via location objects and when live edits are refused on tracked-revision paragraphs.

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