Skip to main content
Glama

reserve

Lock files before editing so other agents cannot overlap them; conflicting requests are refused with the holder, reason, and expiry.

Instructions

Reserve files BEFORE editing them: nobody else can reserve anything overlapping them while the reservation lives. Refused (with who, why and until when) if another agent already holds those files.

Args: paths: ABSOLUTE paths: files, folders (all their content) or patterns (C:\...\src\*.py). reason: why, in one sentence. ttl_min: duration in minutes (1 to 1440); asking again extends it. exclusive: False = shared (only other agents' exclusive reservations block 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": {
      "paths": "<paths>",
      "reason": "<reason>"
    },
    "name": "reserve"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathsYes
reasonYes
ttl_minNo
exclusiveNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.8.7
    • changedOutput schema / (root)
      Previous value: -{
      -  "properties": {
      -    "result": {
      -      "title": "Result",
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "result"
      -  ],
      -  "title": "reserveOutput",
      -  "type": "object"
      -}New value: +null
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

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

Goes well past the annotations: it discloses the mutual-exclusion guarantee, the exact refusal payload (who, why, until when), that re-asking extends the TTL, and the shared-vs-exclusive blocking rule. These are non-obvious concurrency semantics the annotations (destructiveHint=false, idempotentHint=false) cannot convey.

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?

Front-loaded with the action and its constraint in the first sentence, refusal behavior second, then a tight Args block. No redundant restatement of the name or filler text; every line adds information an agent needs.

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?

There is no output schema, and the description explains the failure path thoroughly but not the success return (what the reservation handle/id looks like, whether it must be kept for a later release). Given four parameters and lock semantics, that is the one remaining gap.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must carry the load and it does: all four parameters are explained with meaning beyond the schema types — absolute paths with folder/pattern semantics and a concrete glob example, one-sentence reason, ttl_min range 1–1440 with extend-on-repeat behavior, and exclusive=False meaning shared.

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 specific verb and resource ("Reserve files") plus the core effect: an overlapping-exclusive lock for the reservation's lifetime. An agent can tell this creates a lock rather than reading or releasing one, but the description never names the sibling tools (file_reservation_paths, release_file_reservations, reservations) that an agent might confuse it with.

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?

"Reserve files BEFORE editing them" gives a clear triggering condition, and the refusal case ("Refused ... if another agent already holds those files") tells the agent what to expect when the precondition fails. It stops short of naming alternatives, e.g. when to check `reservations` first or when `release` is required.

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