Tirith

Official

Overview Schema Source Related Servers Discussions Admin

claim

Reserve file or directory paths before editing to avoid conflicts with other agents. Use atomic claims, wait for busy paths, and read the attached brief to stay informed of relevant notices and decisions.

Instructions

Lease repo paths to yourself before editing them, atomically: every path becomes yours or none does. A directory covers its contents, and re-claiming a path you hold renews it. ok carries a brief of the unread notices, contracts, decisions and memory notes for those paths, and marks the notices shown as seen: read it before editing. conflict lists each overlapping lease; do not edit, or pass wait_secs so the daemon waits for the paths instead of you retrying. To see who holds a path without taking it use claims_list; to extend leases use renew.

Input Schema

TableJSON Schema

Name	Required	Description
`agent`	Yes	Your stable agent name.
`brief`	No	Attach the brief. Default true.
`paths`	Yes	Repo-relative files or directories. A directory covers everything beneath it.
`reason`	Yes	Why you need these paths; shown to any agent that is refused.
`ttl_secs`	No	Lease length in seconds. Default 600, max 3600.
`wait_secs`	No	On conflict, wait up to this many seconds (max 120) for the paths to free.

Output Schema

TableJSON Schema

Name	Required	Description
`more`	No	Per brief section, how many matching rows were left out; page with the list tools when not zero.
`memory`	No	Brief: up to 5 memory notes about these paths, as digests with an excerpt. Bodies via memory_read.
`status`	Yes	ok: every path is yours. conflict: nothing was claimed. cancelled: a wait whose caller left. invalid: bad input.
`message`	No	Human-readable detail, on most outcomes other than ok.
`notices`	No	Brief: up to 5 unread notices for these paths (id, kind, summary, by). Now marked seen by you.
`claim_id`	No	The new lease; null when every path was only renewed.
`conflicts`	No	On conflict, one per overlapping path: path, overlaps, owner, reason, expires_at.
`contracts`	No	Brief: up to 5 contracts these paths consume (name, version, kind). Bodies via contract_get.
`decisions`	No	Brief: up to 5 decisions affecting these paths (id, title).
`new_paths`	No	Paths claimed by this call.
`expires_at`	No	RFC 3339 end of the lease unless renewed.
`renewed_paths`	No	Paths you already held, renewed.
`absorbed_paths`	No	Paths you held beneath a directory just claimed, folded into it.
`previous_owner`	No	For a new path whose lease another agent lost in the last hour: path, owner, reaped_at. It may be half-edited.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv1.1.2Sep 18, 2026

addedInput schema / properties / agent / description
```
Added value: +"Your stable agent name."
```
addedInput schema / properties / brief / description
```
Added value: +"Attach the brief. Default true."
```

addedInput schema / properties / paths / description

Added value: +"Repo-relative files or directories. A directory covers everything beneath it."

addedInput schema / properties / reason / description

Added value: +"Why you need these paths; shown to any agent that is refused."

addedInput schema / properties / ttl_secs / description

Added value: +"Lease length in seconds. Default 600, max 3600."

addedInput schema / properties / wait_secs / description

Added value: +"On conflict, wait up to this many seconds (max 120) for the paths to free."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "Any result may also carry lost, inbox, inbox_more and persist_error; see guide.",
+  "properties": {
+    "absorbed_paths": {
+      "description": "Paths you held beneath a directory just claimed, folded into it.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "claim_id": {
+      "description": "The new lease; null when every path was only renewed.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "conflicts": {
+      "description": "On conflict, one per overlapping path: path, overlaps, owner, reason, expires_at.",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "contracts": {
+      "description": "Brief: up to 5 contracts these paths consume (name, version, kind). Bodies via contract_get.",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "decisions": {
+      "description": "Brief: up to 5 decisions affecting these paths (id, title).",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "expires_at": {
+      "description": "RFC 3339 end of the lease unless renewed.",
+      "type": "string"
+    },
+    "memory": {
+      "description": "Brief: up to 5 memory notes about these paths, as digests with an excerpt. Bodies via memory_read.",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "message": {
+      "description": "Human-readable detail, on most outcomes other than ok.",
+      "type": "string"
+    },
+    "more": {
+      "description": "Per brief section, how many matching rows were left out; page with the list tools when not zero.",
+      "type": "object"
+    },
+    "new_paths": {
+      "description": "Paths claimed by this call.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "notices": {
+      "description": "Brief: up to 5 unread notices for these paths (id, kind, summary, by). Now marked seen by you.",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "previous_owner": {
+      "description": "For a new path whose lease another agent lost in the last hour: path, owner, reaped_at. It may be half-edited.",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "renewed_paths": {
+      "description": "Paths you already held, renewed.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "status": {
+      "description": "ok: every path is yours. conflict: nothing was claimed. cancelled: a wait whose caller left. invalid: bad input.",
+      "enum": [
+        "ok",
+        "conflict",
+        "not_found",
+        "none",
+        "invalid",
+        "cancelled"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "type": "object"
+}

First observedv1.1.1Sep 18, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Despite the annotation being limited to destructiveHint=false, the description discloses rich behavioral details: atomic all-or-nothing acquisition, directory recursion, renewal on re-claim, the brief's side effect of marking notices as seen, and conflict semantics. This goes far beyond annotation coverage and gives the agent a realistic model of the tool's effects.

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?

The description is dense but every sentence contributes: atomic semantics, directory behavior, renewal, brief contents and side effects, conflict handling, and explicit alternatives. It is front-loaded with the core action and avoids redundancy with the schema.

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?

For a tool with six parameters and non-trivial concurrency semantics, the description covers the essential behavioral context: atomicity, conflicts, waiting, brief behavior, and alternative tools. The presence of an output schema means return values need not be spelled out, and nothing critical is missing for an agent to invoke this tool 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining why wait_secs is used (daemon waits for paths instead of retrying), how paths behave with directories, and that re-claiming renews a lease, which enriches the ttl_secs and paths parameters. It does not cover every parameter, but it supplements the schema well.

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 opens with a specific verb and resource ('Lease repo paths to yourself before editing them') and immediately clarifies the atomic scope. It distinguishes itself from siblings by naming claims_list and renew as alternatives, and the lease terminology is unique among the sibling tools.

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?

Explicitly states when to use this tool ('before editing them'), when not to edit on conflict, and when to use wait_secs. It names the alternative tools for non-taking inspection (claims_list) and extension (renew), giving an agent clear routing guidance.

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