Renew the lease on an item. Call periodically during long work, or the lease expires and another agent may take the item.
Renew the lease on an item. Call periodically during long work, or the lease expires and another agent may take the item.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Item id. | |
| as_agent | No | Subagent name, this call only. |
Changes observed during successful MCP inspections.
v0.2.7Input schema / properties / as_agent / descriptionPrevious value: -"A subagent's own name, this call only."New value: +"Subagent name, this call only."Input schema / requiredRemoved value: -[
- "id"
-]v0.1.12Input schema / properties / as_agent / descriptionPrevious 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."v0.1.10Input schema / properties / as_agentAdded value: +{
+ "description": "Subagent sharing the parent's connection: your own stable name, for this call only (see ddflow_identify).",
+ "type": "string"
+}v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden, and it does disclose the key consequence: skip it and the lease expires and another agent may take the item. It does not disclose the lease duration, how often "periodically" means, what a failed renewal returns, or any permission requirements — significant gaps for a lease-safety tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste: the action is front-loaded and the consequence follows as justification. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-param tool with no output schema and no annotations, the description covers the why and the risk but not the mechanics: lease TTL, expected call frequency, and what a failed renewal signals are all unstated. An agent knows to call it but not how often or how to interpret failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (id and as_agent) are already documented in the schema, and the description adds nothing about their format or behavior. Notably it does not clarify what happens when the optional id is omitted, which is a real ambiguity given zero required parameters, but the baseline for full schema coverage is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: "Renew the lease on an item." That is clearly distinguishable from mutation siblings like ddflow_claim, ddflow_release, or ddflow_complete, since lease renewal is a unique action. It does not name those siblings or define what an "item" is, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete usage trigger: "Call periodically during long work." That tells the agent when to invoke it, which most siblings' descriptions likely lack. It gives no exclusions or alternatives (e.g., what to do instead if the lease is already gone), so no 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.