Skip to main content
Glama
Sign In
delian

ddflow

by delian
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

ddflow_claim

Lease a work item and create its isolated git worktree, refusing when another agent holds it and suggesting alternatives. Prevents conflicting edits on shared files.

Instructions

Lease an item and create its isolated git worktree. Refuses (exit 3) if another agent holds it or an overlapping item, and names what you could take instead. NEVER steals an expired lease: a crashed agent's tree often holds finished work.

Input Schema

NameRequiredDescriptionDefault
idYesItem id to claim, or an open bug id (its fix task is claimed, filed first if none).
noteNoWhat you intend to do.
breakNoBreak a contended, idle lease (work kept).
forceNoOverride a refusal; only to retry after `ddflow_recover` said a crashed agent's tree holds nothing. Forcing past a dependency or live lease lets two agents write one file. Recorded.
globsNoComma-separated path globs this work will write.
queueNoQueue a refused request (FIFO per file).
approvalNoAn agent's way past a refusal --force would override: 'request' asks the operator, then the approval id they answered.
as_agentNoSubagent name, this call only.
resourcesNoPhysical resources this claim holds, e.g. 'gpu:2'; they REPLACE the item's declared ones. Refused (exit 3) when live claims already use the capacity ([schedule] resources), every holder counted.
no_worktreeNoLease the item without creating a worktree. For work that is not a code change — a research or review task.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.2.9
    • addedInput schema / properties / approval
      Added value: +{
+  "description": "An agent's way past a refusal --force would override: 'request' asks the operator, then the approval id they answered.",
+  "type": "string"
+}
    • changedInput schema / properties / id / description
      Previous value: -"Item id to claim."New value: +"Item id to claim, or an open bug id (its fix task is claimed, filed first if none)."
  2. Changed1 schema field changedv0.2.7
    • changedInput schema / properties / as_agent / description
      Previous value: -"A subagent's own name, this call only."New value: +"Subagent name, this call only."
  3. Changed3 schema fields changedv0.2.3
    • addedInput schema / properties / break
      Added value: +{
+  "description": "Break a contended, idle lease (work kept).",
+  "type": "boolean"
+}
    • changedInput schema / properties / force / description
      Previous value: -"Override a refusal. Legitimate only to retry after `ddflow_recover` said a crashed agent's worktree holds nothing. Forcing past a dependency or live lease is how two agents write one file; recorded either way."New value: +"Override a refusal; only to retry after `ddflow_recover` said a crashed agent's tree holds nothing. Forcing past a dependency or live lease lets two agents write one file. Recorded."
    • addedInput schema / properties / queue
      Added value: +{
+  "description": "Queue a refused request (FIFO per file).",
+  "type": "boolean"
+}
  4. Changed3 schema fields changedv0.1.12
    • changedInput schema / properties / as_agent / description
      Previous value: -"Subagent sharing the parent's connection: your own stable name, for this call only (see ddflow_identify)."New value: +"A subagent's own name, this call only."
    • changedInput schema / properties / force / description
      Previous value: -"Override a refusal. Legitimate for exactly one thing: retrying after `ddflow_recover` has told you a crashed agent's worktree holds nothing. Forcing past a dependency or a live lease is how two agents end up writing the same file, and the override is recorded either way."New value: +"Override a refusal. Legitimate only to retry after `ddflow_recover` said a crashed agent's worktree holds nothing. Forcing past a dependency or live lease is how two agents write one file; recorded either way."
    • changedInput schema / properties / resources / description
      Previous value: -"Physical resources this claim holds, e.g. 'gpu:2'. They REPLACE the item's declared resources (recorded on the item, as globs are). Refused (exit 3) when live claims already use the capacity ([schedule] resources) -- every holder counts, you included."New value: +"Physical resources this claim holds, e.g. 'gpu:2'; they REPLACE the item's declared ones. Refused (exit 3) when live claims already use the capacity ([schedule] resources), every holder counted."
  5. Changed2 schema fields changedv0.1.10
    • addedInput schema / properties / as_agent
      Added value: +{
+  "description": "Subagent sharing the parent's connection: your own stable name, for this call only (see ddflow_identify).",
+  "type": "string"
+}
    • addedInput schema / properties / resources
      Added value: +{
+  "description": "Physical resources this claim holds, e.g. 'gpu:2'. They REPLACE the item's declared resources (recorded on the item, as globs are). Refused (exit 3) when live claims already use the capacity ([schedule] resources) -- every holder counts, you included.",
+  "type": "string"
+}
  6. First observedv0.1.0

TDQS

A3.7/5.0
Behavior4/5

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

With no annotations supplied, the description carries the full disclosure burden and does well: it names refusal exit 3, contention and overlap conflicts, and the deliberate refusal to steal expired leases. It omits success-response details and permissions/auth expectations, but covers the critical safety behavior.

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 tight sentences, front-loaded with the action and followed by the critical refusal and expired-lease rules. Every sentence carries useful information with no redundant restatement.

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

Completeness3/5

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

For a ten-parameter leasing tool with no annotations and no output schema, the description explains conflict handling but does not document the successful return (e.g., worktree path or lease state). That is a meaningful gap, though full schema coverage of parameters mitigates it.

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

Parameters3/5

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

Schema coverage is 100%, so all ten parameters are already documented in the input schema. The description adds the claim/worktree concept but no parameter-level detail beyond that, making the baseline 3 appropriate.

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 ('Lease an item') plus the concrete side effect ('create its isolated git worktree'), so an agent can identify it as a claim/lease tool. It does not explicitly differentiate itself from siblings such as ddflow_task or ddflow_bug, falling just short of full sibling routing.

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?

The description implies use when claiming work and explains refusal behavior, including that a refusal names alternatives. However, it never explicitly says when to choose ddflow_claim over sibling tools, leaving selection to inference.

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