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

The annotations already declare destructiveHint=true and idempotentHint=false, so the danger profile is supplied. The description adds genuine value beyond them by stating that Fudge validates the result and refreshes the preview, which tells the agent the edit is checked and the draft preview updates. It stops short of the things that matter most for a destructive multi-edit call: whether the array of edits is applied atomically, and what happens (partial write vs. rejection) when validation fails.

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, zero filler, with the core action and the matching mechanism front-loaded. "Change part of" is slightly soft where "replace exact text" is the real operation, but nothing in the text 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 destructive, non-idempotent mutation tool with five parameters and no output schema, the description covers the mechanism and notes that validation and preview refresh follow. It leaves out failure/atomicity behavior across the batch of up to 50 edits and any mention of the revision-based concurrency parameter, both of which an agent needs to call this safely.

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 schema already documents path examples, the fudge:// draft ref, old_string/new_string/replace_all, store, and revision. The description contributes only the framing that matching is exact text with no line numbers, which reinforces old_string semantics but adds no format, escaping, or batch-ordering guidance 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?

"Change part of a theme file or .entities document in a Fudge draft by replacing exact text, without line numbers" gives a specific verb (replace), the resource (files inside a draft), and the mechanism (exact-text, not line-based). It does not differentiate itself from the close sibling edit_draft_content, so an agent cannot tell from the description alone which of the two editing tools 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?

Usage is implied through the mechanism: exact-string replacement is the stated way to edit, and the absence of line numbers narrows the tool to safe, position-independent edits. There is no explicit when-to-use vs. edit_draft_content or write_draft_file, and no stated prerequisites such as reading the file first to obtain a revision.

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