AutoCAD MCP Pro

Overview Schema Source Related Servers Discussions Admin

Find and Replace Text

text_find_replace

Find and replace literal text across model space, layouts, block definitions, and attributes, with dry-run preview and revision-guarded apply.

Instructions

Replace text in TEXT, MTEXT and block attributes (ATTRIB and ATTDEF).

Both engines search the same places (searched_scope): model space, every paper layout, every named block definition - so the next insert does not reintroduce the old text - and the attributes of every block reference in any of them; an xref's block holds another file's text and is not searched. searched_types is on the response because "no matches" and "that type was never searched" are different answers. DIMENSION text is out of scope: its text field holds the <> override placeholder rather than the measurement, so editing it would break the association. Anonymous blocks (*D - a dimension's rendered measurement - *T, *U, *X) are renderings regenerated from their owner and are not searched either. A multi-line attribute is matched and rewritten as the whole value (Line1\PLine2), the same value block_get_attributes reports and block_explode bursts.

dry_run=True adds preview: the document's content revision, the exact fingerprint of every matched entity and the planned rows. Applied with that revision (expected_revision) and/or its preconditions, the search runs again first: an edited entity, a moved revision or a new match the preview did not list refuses the call with kind stale_revision and nothing is replaced. A guarded apply reports revision ({checked, after, interleaved}).

Input Schema

Name	Required	Description
`find`	Yes	Literal text to search for (not a regex).
`layer`	No	Restrict to one layer. Empty searches every layer.
`dry_run`	No	Report what would change, with a `preview` to apply it by; change nothing.
`replace`	Yes	Replacement text.
`match_case`	No	Case-sensitive search.
`preconditions`	No	A dry run's `preview.preconditions` ({handle, fingerprint} per match): apply only if each is unchanged and nothing else now matches; otherwise refused stale_revision and nothing is replaced.
`expected_revision`	No	Apply only at this content revision (a dry run's `preview.revision`); otherwise refused stale_revision and nothing is replaced.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.7.0Oct 29, 2026

changedInput schema / properties / dry_run / description

Previous value: -"Report what would change without changing it."New value: +"Report what would change, with a `preview` to apply it by; change nothing."

addedInput schema / properties / expected_revision

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Apply only at this content revision (a dry run's `preview.revision`); otherwise refused stale_revision and nothing is replaced."
+}

addedInput schema / properties / preconditions

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "A dry run's `preview.preconditions` ({handle, fingerprint} per match): apply only if each is unchanged and nothing else now matches; otherwise refused stale_revision and nothing is replaced."
+}

Addedv1.5.1Aug 12, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations carry only destructiveHint=false, so the description shoulders the behavior load and does so: exact search scope, multi-line attribute semantics, what dry_run returns, and the stale_revision refusal path under expected_revision/preconditions. This is real context an agent cannot infer from the schema.

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

Conciseness4/5

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

Front-loaded with the one-line purpose, then grouped into scope, exclusions, and guarded-apply behavior — every sentence carries information. Some parenthetical detail (the `*D`/`*T`/`*U`/`*X` expansion and the `Line1\PLine2` example) is dense but earns its place.

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?

Despite an output schema existing, the description still explains the two response fields that drive agent decisions (searched_scope, searched_types) and the revision report shape. For a 7-parameter mutation tool with a preview/apply protocol, nothing an agent needs to call it safely is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining how the guarded-apply parameters interact ('Applied with that `revision` ... and/or its `preconditions`, the search runs again first') and what preview carries. It does not add meaning for find/replace/layer/match_case beyond the 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?

States a specific verb and resource ('Replace text in TEXT, MTEXT and block attributes (ATTRIB and ATTDEF)') and implicitly draws the boundary against single-entity editors like entity_edit_text by scoping to a drawing-wide find/replace. The explicit list of searched containers makes the operation unambiguous before the schema is opened.

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

Usage Guidelines4/5

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

When-not guidance is unusually strong: DIMENSION text, anonymous blocks (*D/*T/*U/*X) and xref-held text are all called out as out of scope with reasons, and the dry_run-then-apply workflow is documented. It stops short of naming the sibling it replaces (entity_edit_text, block_set_attributes), which would have made routing fully explicit.

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

Deploy Server