Skip to main content
Glama
Sign In

SpecStream

by ai.specstream
OverviewDiscussionsAdmin

Save a new version

revise_spec

Saves a change to a saved request as a new version. The save fails if someone changed the request after the caller read it.

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": {
      "expected_revision_id": "<expected_revision_id>",
      "ast": "<ast>",
      "spec_id": "<spec_id>"
    },
    "name": "revise_spec"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoThe revised request in the person's own words. Lists run from this version are named from it. Without it, the lists are named from the reading.
astYes
nameNo
contextNo
spec_idYes
parent_revision_idNoThe revision of the same request that the new version branches from. Without it, the new version branches from the current head. expected_revision_id still protects the current head against concurrent edits.
expected_revision_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / $defs / WordedCondition / description
      Previous value: -"A requirement no catalog field expresses, kept in the person's own words.\n\nSchema is acceleration, never permission: each result's own pages are read\nfor this statement (yes / no / unsure). A yes needs a quote the code finds in\nthe result's own source; a quoted no removes the result; an unconfirmed line\nis delivered marked."New value: +"A requirement no catalog field expresses, kept in the person's own words.\n\nSchema is acceleration, never permission: each result's own pages are read\nfor this statement (yes / no / unsure). A yes needs a quote the code finds in\nthe result's own source; a quoted no removes the result; a line no page\nstates is delivered and marked as not stated on a page."
  2. First observed

TDQS

B3.4/5.0
Behavior4/5

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

Annotations already declare non-read-only, non-destructive, closed-world, so the safety profile is covered. The description adds two genuinely new behavioral facts: the prior version is preserved (a new version is written, not overwritten) and the write is guarded by optimistic concurrency, failing on stale reads. It still omits what a successful save returns (e.g., the new revision id) and any permission requirements.

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 short sentences, no filler, and the outcome (new version) is front-loaded before the failure condition. Every sentence earns its place and there is no repetition of structured fields.

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

Completeness2/5

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

For a tool taking a deeply nested query AST with no output schema and sparse schema descriptions, the definition is thin: it does not explain what a 'saved request' is, how branching via parent_revision_id changes the resulting version history, or what the caller receives on success. Its relationship to adjacent tools (edit_spec, create_spec, get_spec_revision) is left entirely unexplained.

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

Parameters2/5

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

Schema coverage is only 29% across 7 parameters, so the description carries a heavy burden. It does explain expected_revision_id's purpose through the stale-read failure clause, but says nothing about spec_id, ast (a large nested object), name, context, or how parent_revision_id interacts with expected_revision_id — the schema's own note on that parameter is doing all the work.

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?

States a concrete verb+resource ("Saves a change to a saved request") plus the outcome ("as a new version"), which is meaningfully more specific than the title. It never names the sibling edit_spec, so an agent must infer the versioning distinction rather than being told it, and the term "saved request" drifts from the tool name and spec_id parameter.

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 is only implied: the concurrency sentence implies a read-then-revise workflow, but the description never says when to choose revise_spec over edit_spec or create_spec. No prerequisites (permissions, needing an existing spec_id, needing a fetched revision) are stated explicitly.

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

All SpecStream toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources