Skip to main content
Glama
Sign In

AANet

by space.aanet
OverviewDiscussionsAdmin

aanet_acquire_lock

Claim exclusive ownership of a named unit of work so no other sub-agent starts the same thing — call this before starting work, not after. Returns {lease_expires_at, fence} on success, or a 409 if another sub-agent already holds an unexpired lease on the same name (that conflict is free — you are not charged for losing a race).

You do not hold the lock forever: once lease_seconds elapses, anyone can
acquire it out from under you, even if you're still working. Call
aanet_renew_lock periodically while still working, and
aanet_release_lock the moment you're done so others don't wait out the
full lease unnecessarily.

fence is a monotonically increasing token (it grows with every successful acquire of this
name, so a later holder always has a larger one). Pass it to aanet_write_file/
aanet_append_file/aanet_delete_file so the server rejects your write once someone else has
taken the lock over - protection against a paused agent waking up after its lease expired.

Input Schema

NameRequiredDescriptionDefault
nameYesLock name identifying the unit of work, e.g. "process-batch-3".
api_keyYesBearer credential for this workspace: either the owner_key returned once by aanet_create_workspace/aanet_create_trial_workspace, or a sub-key returned by aanet_mint_subkey. Sent under the hood as `Authorization: Bearer <api_key>`. Owner-only tools reject a sub-key with a 403.
workspace_idYesThe workspace_id from aanet_create_workspace or aanet_create_trial_workspace.
lease_secondsYesHow long you hold the lock before it becomes reclaimable by anyone else, 1-3600 seconds.
idempotency_keyNoOptional retry-safety token (any unique string, e.g. a UUID). If a call times out and you repeat it with the same key and the same arguments, the first successful result is returned again without charging a second time. Keys are remembered for 24 hours, per sub-key. Reusing a key with different arguments is an error (code=IDEMPOTENCY_KEY_REUSED).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / idempotency_key
      Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 255,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional retry-safety token (any unique string, e.g. a UUID). If a call times out and you repeat it with the same key and the same arguments, the first successful result is returned again without charging a second time. Keys are remembered for 24 hours, per sub-key. Reusing a key with different arguments is an error (code=IDEMPOTENCY_KEY_REUSED).",
+  "title": "Idempotency Key"
+}
  2. Changed6 schema fields changed
    • addedInput schema / properties / api_key / description
      Added value: +"Bearer credential for this workspace: either the owner_key returned once by aanet_create_workspace/aanet_create_trial_workspace, or a sub-key returned by aanet_mint_subkey. Sent under the hood as `Authorization: Bearer <api_key>`. Owner-only tools reject a sub-key with a 403."
    • addedInput schema / properties / lease_seconds / description
      Added value: +"How long you hold the lock before it becomes reclaimable by anyone else, 1-3600 seconds."
    • addedInput schema / properties / lease_seconds / exclusiveMinimum
      Added value: +0
    • addedInput schema / properties / lease_seconds / maximum
      Added value: +3600
    • addedInput schema / properties / name / description
      Added value: +"Lock name identifying the unit of work, e.g. \"process-batch-3\"."
    • addedInput schema / properties / workspace_id / description
      Added value: +"The workspace_id from aanet_create_workspace or aanet_create_trial_workspace."
  3. First observed

TDQS

A4.8/5.0
Behavior5/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 so: it discloses lease expiry semantics (lock becomes reclaimable after lease_seconds even mid-work), the 409 conflict response, the cost model for conflicts, the monotonic fence token, and the fence-passing contract with the write tools that enforces stale-writer protection. This is unusually rich behavioral context.

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?

Three tight paragraphs, front-loaded with the primary action and its timing rule, followed by lease lifecycle and then the fence/return contract. Dense with useful detail and little waste, though the fence paragraph could be marginally tightened.

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?

Although there is no output schema, the description documents the success return shape ({lease_expires_at, fence}), the failure mode (409), and the cross-tool contract for using fence. Combined with 100% schema coverage, an agent has everything needed to call this correctly.

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%, so the baseline is 3. The description adds meaning beyond the schema by tying lease_seconds to the reclaim/renew/release lifecycle and by explaining fence (a return value the caller must thread into write calls). Name and api_key semantics are already fully covered by 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?

States a specific verb and resource — 'claim exclusive ownership of a named unit of work' — and explicitly frames the intent ('so no other sub-agent starts the same thing'). It is clearly distinguishable from siblings like aanet_renew_lock, aanet_release_lock, and aanet_get_lock_status, which it names or implies by contrast.

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?

Gives explicit timing guidance ('call this before starting work, not after') and routes the agent to the correct siblings for follow-up actions: aanet_renew_lock while still working, aanet_release_lock the moment work is done. It even clarifies that a lost race (409) is not charged, removing uncertainty about retrying.

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

All AANet toolsInspect
Try in Browser
Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources