Skip to main content
Glama
julianbei

ARNO

by julianbei
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

arno.replace_text

Destructive

Replace an exact, unique string in a file. Refuses if the anchor is missing or matches more than once, so extend it with surrounding context to disambiguate.

Instructions

Replace an exact, unique string in a file. An anchor string does not move when the lines around it do, which is why follow-up edits address text rather than line numbers. Refuses when the anchor is absent or matches more than once — extend it with surrounding context to disambiguate. For several sites, use apply: atomic, one validation, no diagnostics from half-done intermediate states.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pathYesFile path to edit.
rootNoWorktree for this call. Default: the one set with workspace, else the start tree.
newTextYesReplacement text.
oldTextYesExact text to replace. Must appear exactly once.
expectedDigestNoOptional. The digest from the read this edit is based on; the edit is refused if the file changed since, by anyone.
expectedRevisionNoRevision expected before editing.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.0.17
    • changedInput schema / properties / root / description
      Previous value: -"Worktree of this repository to act in. Defaults to the session's workspace."New value: +"Worktree for this call. Default: the one set with workspace, else the start tree."
  2. Changed1 schema field changedv0.0.15
    • addedInput schema / properties / root
      Added value: +{
+  "description": "Worktree of this repository to act in. Defaults to the session's workspace.",
+  "type": "string"
+}
  3. Addedv0.0.12

TDQS

A4.3/5.0
Behavior4/5

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

With destructiveHint=true already declared, the description adds genuinely non-obvious behavior: the tool refuses when the anchor is absent or matches more than once, and apply performs one atomic validation with no half-done intermediate states. It does not mention the concurrency guards, though those are documented on expectedDigest/expectedRevision in the schema. Solid added context, minor gap.

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?

Three sentences, front-loaded with purpose, then rationale, then failure mode, then alternative. Every sentence contributes. The trailing "apply: atomic, one validation, no diagnostics from half-done intermediate states" is slightly compressed/ambiguous in phrasing but still compact for the information delivered.

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

Completeness4/5

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

For a 6-parameter mutation tool with no output schema, the description covers the key risks: uniqueness of the anchor, refusal conditions, disambiguation strategy, and the multi-site alternative. Concurrency/expected-state handling is left to the schema, which is acceptable given 100% coverage, but the description never signals that staleness causes refusal.

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

Parameters3/5

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

Schema description coverage is 100%, so all six parameters are already documented, including the exact-once requirement for oldText and the digest/revision guards. The description reinforces the anchor concept but introduces no syntax, format, or constraint beyond what the schema states. Baseline 3 applies when the schema carries the parameter burden.

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 an exact, unique string in a file") with the uniqueness constraint baked in. It explains the anchor model (text doesn't move when lines shift) and thereby distinguishes itself from line-number based siblings like insert. An agent can tell it apart from arno.insert and arno.apply without opening a schema.

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?

Names an alternative explicitly and the condition that selects it: "For several sites, use apply: atomic". It also gives a concrete recovery path when the tool refuses ("extend it with surrounding context to disambiguate"). Both the routed-away case and the disambiguation case are covered.

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

Deploy Server

Other Tools