agentleFS

Manage agent identities

identity_write

Take, renew or give up the seat you drive an agent from, create an agent below you, put an agent to sleep or wake it, set what an agent below you loads when it connects, publish your capability card, or start a fresh session. Actions — spawn: create a child identity with a SUBSET of what you may do (display, scope: role@location, repeatable) and return its first credentials once; bootstrap_key=true also mints a long-lived key for a headless agent, dead when the child is retired; load_memory_and_skills names the folders whose memory and skills it is handed when it connects (absent: the organization's default). set_card: publish a new version of your capability card; wake_channel=webhook posts signed wake-ups to webhook_url, any URL you give. sleep: put yourself or an agent below you (target) to sleep: its messages and waits stay, but no session may drive it until it wakes; until=reply (default) also wakes it when one of its waits resolves, until=woken only when someone above it wakes it. wake: wake an asleep agent below you (target), so a session may take it up again. take_seat: become the one session driving this agent (yourself, or one below you with acting_as): returns a seat token to pass as seat on every call, the agent's home folder and the end of its journal to read first. A persistent or intermittent agent's writes are refused without its current seat; refused while another session holds it unless take_over=true. renew_seat: extend the lease of the seat you hold (pass its token as seat); never shortens it. release_seat: give up the seat you hold (pass its token as seat), so the next session need not wait out the lease. journal: append a dated entry to your own journal, in your home folder (entry: what you decided and why); take_seat hands its end to the next session. new_session: start a fresh session, so what you read before is not a label on what you write next. update: set which folders an identity below you loads when it connects (target, load_memory_and_skills: folder locations you can read, [] for nothing); never your own: an identity does not widen what it loads. org_context: admins: set the folders a new agent loads when its spawn names none (load_memory_and_skills) and whether answers name the memory and skills of the folders they touch (folder_hints).

Input Schema

Name	Required	Description
`seat`	No	the seat token identity_write action=take_seat gave you; pass it on every call while you drive that agent
`entry`	No	journal: with journal: what you decided and why, or what the next session must know
`scope`	No	spawn: role@location, repeatable; role is viewer, editor or manager (reader, writer and approver are deprecated aliases), e.g. editor@specs/api.md or viewer@*
`until`	No	sleep: what wakes it: reply (default: a reply or anything else that resolves one of its waits, or someone above it) or woken (only someone above it)
`action`	Yes	what to do; each action takes the arguments its line names
`reason`	No	why you are doing this, in one line (at most 200 characters); recorded with the event and exported with the log
`target`	No	sleep, wake, update: an identity id; defaults to you
`vendor`	No	spawn, set_card: who makes the agent, e.g. anthropic
`display`	No	spawn: the child's name
`lease_s`	No	take_seat, renew_seat: how long the seat is yours before you must renew it, in seconds (default 600)
`purpose`	No	spawn, set_card: what it is for
`acting_as`	No	an agent identity below you (its id, from identity_write action=spawn) to make this one call as, with that agent's narrower access; for a helper whose session signs in as its person
`lifecycle`	No	spawn: persistent, intermittent (default) or ephemeral
`risk_tier`	No	spawn, set_card: low, standard (default) or high
`take_over`	No	take_seat: take the seat even though another session holds it; that session's next write is refused
`expires_at`	No	spawn: ISO time the child ends; never later than yours
`environment`	No	spawn, set_card: where it runs, e.g. ci or laptop
`webhook_url`	No	set_card: with wake_channel=webhook: the URL wake-ups are POSTed to, signed
`capabilities`	No	spawn, set_card: what it can do, for role:<capability> addressing; repeatable
`folder_hints`	No	org_context: whether answers name the memory and skills of the folders they touch (default true)
`wake_channel`	No	set_card: how you are woken when a wait resolves: brief (default), sse or webhook
`bootstrap_key`	No	spawn: also mint a long-lived afs_ key bound to the child, for a headless agent. Lives until the child's expires_at, at most 365 days; 90 days when the child has no expiry
`idempotency_key`	No	Any unique string you choose for this write, e.g. a UUID. If you retry the call with the same key and the same arguments, the first answer is returned and nothing is done twice. Reusing a key for a different request is refused. Keys are kept 24 hours.
`refresh_window_s`	No	spawn: how long the child may idle and still refresh, in seconds
`load_memory_and_skills`	No	spawn, update, org_context: folders (locations, ids or links) whose memory (CLAUDE.md, AGENTS.md) and skill names the identity is handed when it connects; each must be one you can read. On spawn, absent means the organization's default; on update, [] loads nothing; on org_context, the default for new agents. A console link (`/d/<Name-Slug>-<32 hex>`, whole or just its id) is accepted too.

Output Schema

Name	Required	Description
`card`	No
`home`	No	your home folder: your journal and standing instructions, read only by you and those above you
`seat`	No
`cards`	No
`ended`	No
`loads`	No
`action`	Yes	the action that answered
`journal`	No	with take_seat: the end of your journal, newest last; read it before you carry on
`identity`	No
`position`	No
`sessionId`	No
`orgContext`	No
`credentials`	No
`journalEntry`	No
`retiringUntil`	No
`webhookSecret`	No	with a webhook: deliveries are signed in the Standard Webhooks format (webhook-id, webhook-timestamp, webhook-signature); verify them with any Standard Webhooks library and this secret

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 30, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed38 schema fields changedOct 24, 2026

changedInput schema / properties / action / enum

Previous value: -[
-  "spawn",
-  "set_card",
-  "new_session",
-  "update",
-  "org_context"
-]New value: +[
+  "spawn",
+  "set_card",
+  "sleep",
+  "wake",
+  "take_seat",
+  "renew_seat",
+  "release_seat",
+  "journal",
+  "new_session",
+  "update",
+  "org_context"
+]

addedInput schema / properties / entry

Added value: +{
+  "description": "journal: with journal: what you decided and why, or what the next session must know",
+  "maxLength": 20000,
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / lease_s

Added value: +{
+  "description": "take_seat, renew_seat: how long the seat is yours before you must renew it, in seconds (default 600)",
+  "maximum": 86400,
+  "minimum": 60,
+  "type": "integer"
+}

addedInput schema / properties / seat

Added value: +{
+  "description": "the seat token identity_write action=take_seat gave you; pass it on every call while you drive that agent",
+  "maxLength": 64,
+  "type": "string"
+}

addedInput schema / properties / take_over

Added value: +{
+  "description": "take_seat: take the seat even though another session holds it; that session's next write is refused",
+  "type": "boolean"
+}

changedInput schema / properties / target / description

Previous value: -"update: an identity id; defaults to you"New value: +"sleep, wake, update: an identity id; defaults to you"

addedInput schema / properties / until

Added value: +{
+  "description": "sleep: what wakes it: reply (default: a reply or anything else that resolves one of its waits, or someone above it) or woken (only someone above it)",
+  "enum": [
+    "reply",
+    "woken"
+  ],
+  "type": "string"
+}

removedOutput schema / properties / ended / properties / heir / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / ended / properties / heir / type
```
Added value: +[
+  "string",
+  "null"
+]
```

addedOutput schema / properties / home

Added value: +{
+  "description": "your home folder: your journal and standing instructions, read only by you and those above you",
+  "type": "string"
+}

addedOutput schema / properties / identity / properties / handle

Added value: +{
+  "description": "an agent's name in the organization: address it as @handle",
+  "type": [
+    "string",
+    "null"
+  ]
+}

removedOutput schema / properties / identity / properties / lastSeenAt / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / identity / properties / lastSeenAt / type
```
Added value: +[
+  "string",
+  "null"
+]
```

addedOutput schema / properties / identity / properties / sleepUntil

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "woken",
+        "reply"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "when asleep: what wakes it"
+}

addedOutput schema / properties / identity / properties / status / description

Added value: +"live, asleep (nothing drives it until it is woken), retired or dead"

addedOutput schema / properties / journal

Added value: +{
+  "description": "with take_seat: the end of your journal, newest last; read it before you carry on",
+  "type": "string"
+}

addedOutput schema / properties / journalEntry

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "at": {
+      "type": "string"
+    },
+    "location": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "location",
+    "at"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / position / properties / ancestors / items / properties / handle

Added value: +{
+  "description": "an agent's name in the organization: address it as @handle",
+  "type": [
+    "string",
+    "null"
+  ]
+}

removedOutput schema / properties / position / properties / ancestors / items / properties / lastSeenAt / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / position / properties / ancestors / items / properties / lastSeenAt / type
```
Added value: +[
+  "string",
+  "null"
+]
```

addedOutput schema / properties / position / properties / ancestors / items / properties / sleepUntil

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "woken",
+        "reply"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "when asleep: what wakes it"
+}

addedOutput schema / properties / position / properties / ancestors / items / properties / status / description
```
Added value: +"live, asleep (nothing drives it until it is woken), retired or dead"
```

addedOutput schema / properties / position / properties / children / items / properties / handle

Added value: +{
+  "description": "an agent's name in the organization: address it as @handle",
+  "type": [
+    "string",
+    "null"
+  ]
+}

removedOutput schema / properties / position / properties / children / items / properties / lastSeenAt / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / position / properties / children / items / properties / lastSeenAt / type
```
Added value: +[
+  "string",
+  "null"
+]
```

addedOutput schema / properties / position / properties / children / items / properties / sleepUntil

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "woken",
+        "reply"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "when asleep: what wakes it"
+}

addedOutput schema / properties / position / properties / children / items / properties / status / description
```
Added value: +"live, asleep (nothing drives it until it is woken), retired or dead"
```

addedOutput schema / properties / position / properties / self / properties / handle

Added value: +{
+  "description": "an agent's name in the organization: address it as @handle",
+  "type": [
+    "string",
+    "null"
+  ]
+}

removedOutput schema / properties / position / properties / self / properties / lastSeenAt / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / position / properties / self / properties / lastSeenAt / type
```
Added value: +[
+  "string",
+  "null"
+]
```

addedOutput schema / properties / position / properties / self / properties / sleepUntil

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "woken",
+        "reply"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "when asleep: what wakes it"
+}

addedOutput schema / properties / position / properties / self / properties / status / description
```
Added value: +"live, asleep (nothing drives it until it is woken), retired or dead"
```

addedOutput schema / properties / position / properties / siblings / items / properties / handle

Added value: +{
+  "description": "an agent's name in the organization: address it as @handle",
+  "type": [
+    "string",
+    "null"
+  ]
+}

removedOutput schema / properties / position / properties / siblings / items / properties / lastSeenAt / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
addedOutput schema / properties / position / properties / siblings / items / properties / lastSeenAt / type
```
Added value: +[
+  "string",
+  "null"
+]
```

addedOutput schema / properties / position / properties / siblings / items / properties / sleepUntil

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "woken",
+        "reply"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "when asleep: what wakes it"
+}

addedOutput schema / properties / position / properties / siblings / items / properties / status / description
```
Added value: +"live, asleep (nothing drives it until it is woken), retired or dead"
```

addedOutput schema / properties / seat

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "clientName": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "epoch": {
+      "description": "raised on every take; a write under an older one is refused",
+      "type": "number"
+    },
+    "expiresAt": {
+      "description": "renew before then (renew_seat), or the seat is free for the next session",
+      "type": "string"
+    },
+    "token": {
+      "description": "with take_seat: pass it as `seat` on every call while you drive this agent",
+      "type": "string"
+    }
+  },
+  "required": [
+    "epoch",
+    "expiresAt",
+    "clientName"
+  ],
+  "type": "object"
+}

Changed1 schema field changedOct 16, 2026

addedInput schema / properties / acting_as

Added value: +{
+  "description": "an agent identity below you (its id, from identity_write action=spawn) to make this one call as, with that agent's narrower access; for a helper whose session signs in as its person",
+  "type": "string"
+}

AddedOct 6, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Annotations only declare the broad safety profile (non-read-only, non-destructive, non-idempotent, open-world); the description goes well beyond that with refusal semantics (writes refused without a seat, refused while another session holds it), lease renewal behavior, bootstrap key lifetime tied to child retirement, scope subsetting on spawn, and signed webhook wake-ups. These are exactly the behavioral traits an agent needs before invoking a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single paragraph bundles 11 actions and their parameters into dense em-dash prose, making it hard to scan and forcing the reader to parse inline instead of per-action structure. It is front-loaded with an action menu and little is filler, but the wall-of-text format costs readability.

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 25 parameters, 11 actions, and an output schema, the description covers the behaviorally critical paths (seat lifecycle, spawn, sleep/wake, journal) thoroughly. It leaves less-risky parameters such as idempotency_key, lease_s, expires_at, and risk_tier to the schema, which is acceptable given 100% schema coverage. Enough is present that an agent can call the tool correctly, though a per-action argument map would make it fully complete.

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 cross-action semantics the schema cannot: seat tokens must be passed on every call, scope is role@location and must be a subset of your own rights, and load_memory_and_skills means different things per action (absent = org default on spawn, [] = nothing on update, org default on org_context). It also states 'never your own' for update, which is a real constraint beyond the parameter docs.

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?

The description names the concrete resource (agent identities) and enumerates each verb it can perform: take/renew/release seat, spawn, sleep, wake, set_card, journal, new_session, update, org_context. An agent can tell it is not access_write or coordination_write because every action concerns identity lifecycle and seats. It does not explicitly contrast with those siblings, keeping it at 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Each action carries its own usage condition: seat is required for persistent/intermittent writers, take_over is needed when another session holds the seat, update never applies to yourself, until=reply vs woken define what wakes a sleeping agent. There is clear context for when each action applies. What is missing is explicit routing against alternative tools, so 4 is appropriate.

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

All agentleFS tools Inspect

Try in Browser

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold 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

Need Help?