Server Quality Checklist

Tool Scores

• file_readA
  3.5/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It discloses that content returns via JSON, avoids shell/escaping issues, and caps output at 2000 lines. It does not mention error handling, permission requirements, or what happens when the cap is exceeded (truncation vs. error).

  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?

  Three sentences with no wasted words. The core function is front-loaded, followed by key behavioral notes on JSON safety, line ranges, and output cap. Every sentence contributes meaningful information.

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

  Completeness3/5

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

  The tool is simple and parameters are fully documented, so the description is mostly adequate. However, with no output schema, the description does not specify the JSON structure of the response or how oversize files are handled beyond the 2000-line cap, leaving some ambiguity.

  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 coverage is 100%, so the schema already documents all parameters. The description adds minor value by suggesting line ranges for large files, but it doesn't enrich the semantics of path or line numbers beyond the schema.

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

  Purpose4/5

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

  The description clearly states a specific verb ('Read') and resource ('file'), including the ability to read an entire file or a line range. It doesn't explicitly name sibling tools, but the distinction from shell-based reads is implicit through 'no shell, no escaping issues.' This is clear but not as strong as naming alternatives.

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

  Usage Guidelines3/5

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

  The description gives context for using start_line/end_line on large files and implies a safer alternative to shell-based reads, but it doesn't explicitly state when to use this tool versus file_search or shell_exec. Usage guidance is present but mostly implied rather than explicit.

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

• shell_execA
  3.5/5.0
  Behavior2/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It acknowledges arbitrary execution, suggesting broad power, but does not mention side effects, destructive potential, return values, error behavior, or timeout implications. The guardrail sentence is a usage rule, not a disclosure of what happens when the command runs.

  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?

  Three sentences, each earning its place: the action, the intended use case, and the explicit guardrails. It is front-loaded and compact with no redundant filler.

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

  Completeness3/5

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

  The description covers purpose and usage boundaries well, but with no output schema it does not state what the agent should expect back (stdout/stderr, exit codes, errors). It also does not disclose side-effect risks beyond the vague inference from 'arbitrary,' which is notable for a shell execution tool.

  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 parameters are already documented with defaults and constraints. The description adds no extra parameter-level meaning beyond describing commands as 'arbitrary shell commands,' which aligns with the schema's 'command' field. Baseline 3 is appropriate.

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

  Purpose4/5

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

  The description names a specific action ('Execute arbitrary shell commands') and a target ('Termux device'), and frames its intended use as 'direct filesystem inspection and diagnostics.' It does not explicitly distinguish itself from sibling file tools, but the verb and resource are clear enough for an agent to understand what shell_exec does.

  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?

  Strong guardrails are present: 'Only call when the user has explicitly requested execution, or when diagnostics are clearly required' and 'Do not use for speculative exploration or as a default first step.' It does not name alternative tools like file_read for inspection, so it misses the explicit-alternatives element of a top score.

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

• agent_controlA
  3.7/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It usefully discloses the API mechanism and the error behavior with CLI fallback instructions. However, it says nothing about the disruptive consequences of abort/reset/compact (e.g., potential context or state loss) or any prerequisites/auth requirements, which is significant for a tool that mutates running sessions.

  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?

  Two tight sentences with the purpose and action list front-loaded, followed by error behavior. The clause 'Uses the gateway /tools/invoke API' is an implementation detail that adds little for an agent deciding to call the tool, but the rest is efficient and earns its place.

  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 3-param tool with no annotations and no output schema, the description covers action semantics, conditional parameter requirements (via schema), and error/fallback behavior. It stops short of stating per-action side effects or the response format, but an agent has enough to decide whether and how to invoke it correctly.

  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 coverage is 100%, so the baseline is 3 and the schema already documents the action enum and the message requirement for steer. The description adds marginal semantic color ('abort stuck agents', 'compact their context'), but does not materially exceed what structured fields provide.

  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 ('Control') + resource ('running agent sessions') and enumerates four concrete actions: abort, steer, compact, reset. This distinguishes it from siblings like agent_dispatch (starting agents) and agent_query (inspecting agents) without needing to open their schemas.

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

  Usage Guidelines3/5

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

  'Running agent sessions' implies the tool applies to already-dispatched agents, and the action list hints at when each is appropriate (e.g., abort for stuck agents). However, the description never explicitly contrasts it with agent_dispatch or agent_query, nor states when not to use it; routing is left to inference.

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

• agent_queryA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden. It accurately signals a read-only observation tool and reveals data sources (sessions.json, JSONL, gateway/command/heartbeat logs), but it does not explicitly state that no state is modified or describe output/error behavior.

  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?

  A one-line summary followed by five tightly scoped bullets. Every bullet names a view and its core deliverable, and there is no filler or repeated schema detail.

  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?

  Given the multi-view complexity and absence of an output schema or annotations, the description covers the key decision points: what each view returns and the underlying data sources. Minor omissions like response shapes and explicit read-only confirmation keep it just short of complete.

  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 the input schema already documents all seven parameters. The description adds view-level meaning but does not provide parameter semantics beyond what the schema, enums, and defaults already encode.

  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 opening sentence names a concrete resource ('agent observation') and a specific composition verb ('consolidates'), and each bullet defines a distinct view. The set of observation views clearly separates it from sibling action tools like agent_dispatch and agent_control.

  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?

  The view list provides clear context for when to call this tool: health, sessions, actions, logs, or history are all routed here. It does not explicitly exclude alternatives or name sibling tools for competing cases, but the consolidated-scope framing makes the intended use clear.

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

• openclaw_cliA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral disclosure burden. It does this well by noting that config_set writes over SSH, that config_get reads directly from the filesystem, that restart cannot be performed remotely and returns instructions, and that doctor runs over SSH. It also mentions safety characteristics like CLI validation, but does not go into detail about side effects or failure modes.

  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 well-structured with a brief overview followed by bullet-style explanations for each command. Each sentence earns its place by adding operational detail, and the most important decision-relevant differences are front-loaded.

  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?

  The description covers all five commands and their mechanics, which is sufficient for selecting and invoking the tool correctly. Since there is no output schema, it could have said more about return values or output formats, but for a multi-command tool with rich schema coverage, the description is largely complete.

  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 coverage is 100%, and parameter descriptions already document each parameter thoroughly with examples, so the description adds limited additional semantic value. It reinforces command-specific context, such as direct filesystem reads versus SSH writes, which helps interpret parameters like key and value, but the schema already carries the main 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?

  The description clearly identifies the tool as performing OpenClaw CLI operations and enumerates each distinct command with a concise explanation. It is immediately distinguishable from sibling tools like agent_dispatch or shell_exec, and even differentiates sub-commands like config_get versus config_set.

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

  Usage Guidelines3/5

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

  The description gives useful guidance on when to use each sub-command, especially config_get versus config_set based on safety and speed trade-offs. However, it does not explicitly say when to use this tool instead of related siblings like shell_exec or system_health, leaving that comparison to inference.

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

• agent_dispatchA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden and does well: it discloses fire-and-forget behavior, blocking behavior, return payloads (runId + childSessionKey), and Telegram support. It does not detail failure modes, authorization needs, or side effects of dispatching an agent, but the core operational behavior is transparent.

  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 compact and well-structured, leading with the core action, then listing modes with line breaks, and ending with routing and usage condition. Every sentence contributes useful information without repetition or fluff.

  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?

  Given the complexity (14 parameters, 3 modes, no annotations, no output schema), the description is largely complete: it covers modes, routing, and when to call. It stops short of describing exact return shapes for sync mode and error or edge-case behavior, which a fully complete definition might include.

  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 description coverage is 100% and each parameter already has detailed descriptions, so the baseline is 3. The main description adds value by explaining mode semantics (async/sync/spawn) and how parameters relate to those modes, which goes beyond the schema's enum lists and defaults.

  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 states a specific verb and resource ('Send a task or message to an OpenClaw agent') and immediately distinguishes three modes, so an agent knows exactly what the tool does. It also names the target agents (Tani, Alan, Rachel), which further separates it from siblings like agent_query and agent_control.

  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?

  The description gives a clear invocation condition ('Only call when the user has explicitly requested execution') and explains when each mode is appropriate (async, sync, spawn). However, it does not explicitly contrast this tool with alternative sibling tools or say when not to use it in favor of them, which keeps it from a 5.

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

• file_searchA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral disclosure burden. It discloses case-insensitivity, literal (non-regex) matching, recursive directory behavior, and return of structured hits with context lines. It could mention stop-after-max behavior or permissions, but the disclosed traits cover the core operation well.

  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?

  Three sentences with no fluff. The primary action and scope are front-loaded, and each sentence adds distinct value: search behavior, return shape, case sensitivity, and alternative tool routing.

  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 moderately complex search tool with no output schema, it explains the result type ('structured hits with surrounding context lines') and all key selector behaviors. It is slightly vague about the exact output format and edge cases, but the combination of description and fully documented schema is adequate for correct invocation.

  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 the schema already documents all five parameters thoroughly. The description adds behavioral context like case-insensitivity and literal matching, but it does not add substantial parameter-level meaning beyond what the schema provides.

  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 uses a specific verb ('Search') and identifies the exact resource scope: a literal string in a file or recursively in a directory. It also distinguishes itself from shell_exec by explicitly punting regex searches to that sibling, so agents can disambiguate without reading schemas.

  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?

  It states when to use this tool ('Replaces grep -n') and explicitly names the alternative for a different case ('For regex searches, use shell_exec'). This gives clear selection criteria among the sibling tools.

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

• system_healthA
  4.4/5.0
  Behavior4/5

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

  No annotations are present, so the description fully carries the burden of behavioral context. 'Fast and read-only — safe to call any time' explicitly discloses the safety profile and operation cost. It also lists gateway reachability and process checks, which hint at possible network and process inspection behavior. It does not define the output shape or whether network calls are made, but for a zero-argument health snapshot, disclosure is above average.

  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?

  Two sentences, front-loaded with 'Snapshot' and the substance in a comma-separated list; the safety note lands last. Every word earns its place, no filler or redundant restatement of the name.

  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?

  The tool is trivial in complexity (0 params, no output schema, no annotations), and the description covers what it does, its performance, and safety. The only minor gaps are lack of a stated output format and not explicitly saying it does not modify state beyond 'read-only', which is already implicit. Near-complete for this simplicity tier.

  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?

  The tool has zero parameters, so there is no schema burden. The description establishes that the tool can be invoked anytime with no required inputs and elaborates what the call returns conceptually. This is the appropriate baseline for a parameterless tool.

  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 clear 'Snapshot of Termux device health' and enumerates the exact resource categories (RAM, CPU load, disk space, OpenClaw version, gateway reachability, processes). This is a specific verb-resource reading that distinguishes it from siblings like agent_dispatch or file_read; nothing in the sibling list overlaps with health diagnostics.

  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?

  The phrase 'safe to call any time' gives clear contextual guidance without explicitly naming alternatives. Since it is a read-only zero-parameter diagnostics snapshot with no sibling tool serving a similar role, excluding alternatives is less critical; the guidance is clear enough.

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

• file_writeA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the behavioral disclosure burden. It clearly states the overwrite behavior, clarifies that content is passed via JSON parameters and not a shell, and notes automatic parent-directory creation. It does not cover error handling or return values, but the core side effects are transparent.

  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 three purposeful sentences with no filler. It front-loads the core action, then adds safety/behavioral context, then gives routing guidance. Every sentence 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?

  For a two-parameter write tool with 100% schema coverage and no output schema, this description is complete. It covers what the tool does, its safety characteristics, parent-directory side effect, and when to choose it over file_edit.

  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 the schema already documents both path and content. The description adds marginal value by emphasizing JSON parameter handling and full-file content, but it does not meaningfully expand 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?

  The description opens with a specific verb and resource: 'Create or overwrite a file with the given content.' It also differentiates from the sibling file_edit by explicitly positioning this tool for new files and full rewrites, so an agent can distinguish it without inspecting the 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?

  The description gives explicit usage direction: 'Use this for new files and full rewrites.' It also names the alternative, file_edit, for targeted edits, making the when-to-use and when-not-to-use decision direct and unambiguous.

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

• file_editA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden and discloses key behavioral constraints: old_str must match raw file content exactly, must appear exactly once, and new_str can be empty for deletion. It does not mention error behavior if the uniqueness constraint is violated or whether the file is created if absent, but the core mutation behavior is transparent.

  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?

  Two sentences, no filler, with the primary operation stated first and the usage guidance second. Every sentence contributes either an operational constraint or a routing decision, making it highly scannable for an agent.

  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 simple edit tool with fully documented parameters, the description covers the essential constraints and rationale. It does not describe the return value or error handling, and it does not explicitly contrast with file_write, but these are minor gaps given the schema completeness and the clarity of the primary use case.

  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?

  The schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds useful nuance by emphasizing that old_str is matched against the raw file content rather than a rendered/escaped version, and that JSON parameter passing avoids shell escaping pitfalls. This meaningfully supplements 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?

  The description states a specific verb ('Replace'), a specific resource ('a file'), and the precise operation (unique string replacement). It clearly distinguishes file_edit from siblings like file_read and file_write, and from shell-based editing, so an agent can identify when this tool is relevant.

  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?

  It explicitly instructs the agent to use this tool instead of shell-based sed/python for file edits and explains why: content goes through JSON parameters with no escaping issues. This gives a clear when-to-use directive and names the alternatives it replaces.

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