Skip to main content
Glama
Sign In
Swarmail

Swarmail

by bompus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

release_file_reservations

Destructive

Release active file reservations when work is finished so other agents can reserve those paths; omit filters to release all or specify paths/IDs for a subset.

Instructions

Release your active reservations when you finish work so other agents can reserve those paths. While work continues, use renew_file_reservations instead. Omit both filters to release all; supply paths or file_reservation_ids for a subset. Empty filters impose no restriction; two nonempty filters must both match. Returns how many were released; zero is not an error.

Input Schema

NameRequiredDescriptionDefault
pathsNoOnly your reservations with exactly these patterns.
agent_nameYesYour registered agent name.
session_idNoWith session_ended: the ending session's ID. A report from a session that no longer holds this name is ignored; without it the report skips that check.
project_keyYesAbsolute path of the repository's primary checkout.
session_endedNoSet only by the host's SessionEnd hook; agents must not set it. list_agents shows session_ended_at until the agent next sends, reserves, reads its inbox, changes or withdraws mail, or waits again.
file_reservation_idsNoOnly your reservations with these ids.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.6.1
    • addedInput schema / properties / session_ended
      Added value: +{
+  "description": "Set only by the host's SessionEnd hook; agents must not set it. list_agents shows session_ended_at until the agent next sends, reserves, reads its inbox, changes or withdraws mail, or waits again.",
+  "type": "boolean"
+}
    • addedInput schema / properties / session_id
      Added value: +{
+  "description": "With session_ended: the ending session's ID. A report from a session that no longer holds this name is ignored; without it the report skips that check.",
+  "type": "string"
+}
  2. Changed2 schema fields changedv0.2.2
    • addedInput schema / properties / file_reservation_ids / description
      Added value: +"Only your reservations with these ids."
    • addedInput schema / properties / paths / description
      Added value: +"Only your reservations with exactly these patterns."
  3. First observedv0.2.1

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already flag destructiveHint=true, readOnlyHint=false and non-idempotence, so the safety profile is known. The description adds real context beyond that: releasing frees paths for other agents, and a release count of zero is not an error, which prevents false failure handling. It stops short of saying whether the reservation record is deleted outright or just marked released.

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?

Four short sentences, front-loaded with the purpose and the sibling routing, then filter behavior, then return semantics. Nothing is redundant with the annotations or schema.

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?

With no output schema, the description usefully states the return value and the zero-count edge case, and it fully covers filter combination. The host-only session_ended/session_id behavior is left entirely to the schema, which is acceptable but is the one piece an agent might still misjudge from the description alone.

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 coverage is 100%, so the baseline is 3, but the description adds genuine filter semantics the schema does not state: omitting both filters releases everything, empty filters impose no restriction, and two non-empty filters must both match. That AND-vs-OR combination rule is exactly the kind of meaning the schema leaves implicit.

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 names a specific verb and resource ('release your active reservations') plus the outcome ('so other agents can reserve those paths'), which separates it cleanly from renew_file_reservations and list_file_reservations. An agent can pick it without opening 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?

It gives an explicit trigger ('when you finish work') and names the alternative with its own condition ('While work continues, use renew_file_reservations instead'). It also explains the no-filter default versus the subset case, so the selection and scoping decisions are both 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