Skip to main content
Glama
Sign In
Sora Commander

Sora Commander

by kurojack-jp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

preview_source_patch

Preview one literal exact-text source replacement against an expected SHA-256 without writing or approving, and return old/new hashes plus the complete diff for review.

Instructions

Build one literal source edit proposal; no file write or grant.

Use to preview one literal exact-text source replacement against the expected SHA-256. No write/approval. Source up to 65536 bytes; complete diff up to 16384 bytes. Returns old/new SHA-256 and the complete diff, never the whole proposed content. A generic tool failure is not an Owner rejection or a write; resolve stale or ambiguous source rather than guess.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>",
      "old_text": "<old_text>",
      "new_text": "<new_text>",
      "expected_sha256": "<expected_sha256>"
    },
    "name": "preview_source_patch"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesPath to the target within the already-configured Owner read/edit roots; path alone grants no access.
new_textYesLiteral replacement (at most 4096 UTF-8 bytes); may contain secrets. Submitted writes require local Owner review; never a shell command.
old_textYesLiteral existing text (at most 4096 UTF-8 bytes); may contain secrets. Submitted writes require local Owner review; exactly one match.
expected_sha256YesExpected 64-character lowercase SHA-256 of current file content; stale values must fail.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.2

TDQS

A3.9/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full burden and does so well: it discloses no write, no grant, no approval, size ceilings (65536 bytes source, 16384 byte diff), that it returns old/new SHA-256 plus a complete diff but never the full proposed content, and that a generic tool failure is not an Owner rejection. It even instructs the agent to resolve stale/ambiguous source rather than guess, which is exactly the behavior an agent needs on a precondition-checked mutation preview.

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?

The negation and the core action are front-loaded in the first two lines, and every later sentence adds distinct information about limits, return shape, or failure semantics. The telegraphic fragment style ("No write/approval.") is dense but not wasteful, though it reads slightly clipped rather than polished.

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 four-parameter, precondition-guarded preview tool with no annotations, the description covers safety, size limits, return contents, and failure interpretation; the existence of an output schema means return values need not be spelled out further. The remaining hole is sibling differentiation against the other preview and patch-request tools, which is the one thing an agent still has to guess.

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 four parameters including the byte limits and the exactly-one-match rule. The description adds only marginal meaning beyond that, reiterating the expected SHA-256 check and the return of old/new hashes; per the baseline rule this lands at 3.

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 verb and resource ("Build one literal source edit proposal", "preview one literal exact-text source replacement") and states the negated scope (no file write, no grant, no approval). It falls short of a 5 because it never distinguishes itself from the adjacent siblings preview_text_edit, preview_source_create, or request_source_patch_dev, so an agent cannot tell from the text alone which preview tool fits which case.

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?

Usage context is implied by "Use to preview one literal exact-text source replacement against the expected SHA-256", which tells the agent the job is exact-text replacement validation. However there is no explicit when-not clause and no routing advice toward preview_text_edit or request_source_patch_dev, which sit right next to it in the sibling list.

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