One permissioned folder your team and your AI agents both log into.
Scored across 24 tools
Most tools pair a distinct verb with a distinct resource (read_org_doc, write_org_doc, list_org_people, claim_share_link). The risk areas are delete_org_doc vs. erase_org_doc (both remove, differing only in permanence) and connect_org_source vs. add_org_source (sequential steps), but the descriptions are unusually explicit about these boundaries, so a careful agent will not misfire.
The dominant pattern verb_org_noun is followed by 21 of 24 tools (create_org_folder, revoke_org_agent, search_org_knowledge, etc.), giving the set a strong rhythm. The three deviations — list_my_recent_work, undo_delete, and who_can_read — are minor and semantically sensible, so they read as deliberate exceptions rather than chaos.
24 tools sits in the heavy band and covers a very wide surface: documents, folders, sharing, agents, source connectors, and a board system. Each tool appears to earn its place given the broad scope, but the sheer number will tax an agent's selection process, and some subdomains (e.g., sharing) could have been consolidated.
Lifecycle coverage is remarkably thorough: documents have create/edit/read/recoverable-delete/permanent-erase/undo, sharing has grant/revoke/inspect/link-create/link-claim, and agents and sources both have full create-to-retire flows. Minor gaps exist — there is no tool to change an existing share's permission level or move/rename a document — but agents can work around these with revoke-then-share and write-over.
Add an agent to this organization: creates it, gives it one role on a folder, a document or the whole organization, and returns its token. You can only give what you own — a scope you own or one below it. Agents you add may add agents of their own, bounded the same way. Names need not be unique; each agent gets its own id. TWO CALLS: the first previews and creates nothing; call again with its confirm_token to create. The token is shown once, in that answer. Retire the agent with revoke_org_agent when its work is done.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | what to call the agent, e.g. 'seo-bot'. People and agents see this name on the board | |
| role | Yes | reader reads; writer also edits; owner also grants access and adds agents there | |
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| location | No | the folder or document, e.g. 'growth' or 'growth/seo'. Omit for the organization | |
| scope_type | No | default folder. 'organization' is the whole organization and takes no location | |
| confirm_token | No | from the first call. Calling without it PREVIEWS: nothing is created. | |
| expires_in_days | No | how long the agent's token lives, 1–365; default 90 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full behavioral burden and does so thoroughly. It discloses that the tool creates an agent, returns a token shown only once, requires a confirm_token on the second call, allows non-unique names, and explains scope-ownership constraints.
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?
The description is dense yet efficient; every sentence contributes a distinct fact needed to call the tool correctly. It front-loads the purpose and then moves through constraints, naming, the two-call flow, token visibility, and revocation without repetition or filler.
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 7-parameter mutation tool with no annotations and no output schema, the description covers the essential operational context: creation, role assignment, scoping, ownership boundaries, agent inheritance, token handling, and cleanup. The schema handles remaining parameter details, so nothing critical is missing.
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?
Input schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: ownership scoping ('a scope you own or one below it'), non-unique names with independent IDs, and the preview/confirm_token lifecycle. This meaningfully enriches understanding of the parameters.
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?
The description opens with a specific verb and resource: 'Add an agent to this organization: creates it, gives it one role on a folder, a document or the whole organization, and returns its token.' This clearly distinguishes add_org_agent from sibling tools like add_org_source or revoke_org_agent.
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?
The description provides strong usage context: ownership limits, the two-call preview/confirm workflow, and an explicit pointer to revoke_org_agent for retirement. It does not formally contrast with other 'add' tools, but the purpose is clear enough that an agent would know when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
After an account is connected, point one repository or Drive folder at a folder here, so its documents sync in. The destination is a folder you can write to — create_org_folder first if it does not exist. Call list_org_sources afterwards to confirm it ran. Sync is ONE-WAY, from the source into agentleFS, and it repeats: the source is polled and the destination folder is brought up to date. Documents you write here are not pushed back to the repository, and a connector-owned path refuses direct edits rather than having them silently overwritten on the next run.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| branch | No | GitHub only: the branch to follow (default: the repo default) | |
| account | Yes | the connected account, exactly as list_org_sources prints it (the installation or account ref) | |
| location | Yes | the FOLDER this source writes into, whole path from the workspace root, e.g. "handbook" or "handbook/vendor" | |
| provider | Yes | which connected account this source uses | |
| folder_id | No | Google Drive only: the Drive folder id to pull | |
| repo_name | No | GitHub only: the repository name | |
| repo_owner | No | GitHub only: the repository owner |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral disclosure burden. It states that syncing is one-way, repeats via polling, does not push local writes back, and that connector-owned paths refuse direct edits. This gives the agent a clear model of side effects.
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?
Four concise sentences front-load the core action and then cover prerequisite, verification, and sync behavior. Every sentence adds essential information with no filler.
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 tool with 8 parameters and no output schema, the description covers the essential context: when it is used, destination requirements, verification steps, and sync behavior. It gives the agent everything needed to invoke the tool correctly.
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 description coverage is 100%, so the schema already documents every parameter. The description adds high-level context about repositories/Drive folders vs. destinations, but it does not add per-parameter meaning beyond what the schema provides.
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?
The description opens with a concrete action: point one repository or Drive folder at a folder so its documents sync in. It also specifies the prerequisite ('After an account is connected'), which clearly separates this tool from account-connection operations.
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?
It gives clear before/after steps: create_org_folder if the destination does not exist)Skip, and list_org_sources afterwards to confirm. The phrase 'After an account is connected' implies it should not be used to connect accounts, though it does not explicitly name connect_org_source as the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Step one of connecting a source. Returns a link for the USER to open: authorising happens at GitHub or Google, in their browser, and cannot be done for them — give them the link and wait. When they say they are done, call list_org_sources to see the account that arrived, then add_org_source to point one repository or Drive folder at a folder here. list_org_sources again afterwards tells you whether the first sync actually ran.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| provider | Yes | which source to connect: github, or gdrive for Google Drive |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it excels: it discloses that the tool returns an authorization link, that authorization happens in the user's browser, that the agent cannot perform it, and that no immediate connection is established. This directly shapes agent expectations and behavior.
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?
Three dense sentences, front-loaded with 'Step one' and the key output ('Returns a link'). Every sentence earns its place: output, user-action requirement, and follow-up workflow. No filler or repetition.
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?
Despite having no output schema or annotations, the description tells the agent what the tool returns, what cannot happen, what the agent should do next, and how to verify success. This is sufficient for an agent to invoke and follow through on this tool correctly.
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 description coverage is 100%, with provider and token already documented. The description adds no new parameter-level details but does reinforce the provider distinction by naming GitHub and Google, which mirrors the schema enum. Baseline 3 is appropriate.
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?
The description clearly identifies this as 'Step one of connecting a source' and explains that it returns a link for the user to authorize. It distinguishes itself from the sibling add_org_source by positioning connect_org_source as the initiating step, not the actual attachment step.
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?
It explicitly states when to use this tool ('Step one'), what the agent must do ('give them the link and wait'), and what to call next (list_org_sources, then add_org_source, then list_org_sources again). This is precise routing guidance for the multi-step workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make a folder. Use it to start a project before putting anything in it — content goes in a folder and access is granted on one, so the folder is the unit everything else hangs off. You become its owner, which is what lets you share it.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| folder_path | Yes | folder names, outermost first, e.g. ["product-docs"] or ["product-docs","specs"] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full behavioral disclosure burden. It does this well by revealing a meaningful side effect: the caller becomes the folder's owner, which is what enables sharing. It stops short of covering failure conditions, duplicates, or visibility, but the ownership consequence is important and non-obvious.
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?
Three sentences, front-loaded with the core action and then expanded with the conceptual model. Each sentence adds information, though the middle sentence is slightly roundabout ('access is granted on one' is a bit indirect). Overall it is efficient and readable.
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 simple create operation with one required parameter and no output schema, the description is largely complete: it covers purpose, usage timing, and the key ownership consequence. It does not describe return behavior or failure cases, but given the simple shape of the tool this is a minor gap.
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 description coverage is 100%, so the schema already explains both token and folder_path, including ordering and an example. The description adds no additional parameter-level meaning, which is acceptable because the schema carries the load; baseline 3 applies.
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?
The description opens with a clear verb+resource pairing ('Make a folder') and goes further by defining why a folder is created: it is the unit that holds content and carries access for a project. This distinguishes create_org_folder from share/list-related siblings such as share_org_folder and list_org_folders.
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?
It clearly states when to use this tool: to start a project before putting anything in it, since content and access both attach to a folder. It does not explicitly name excluded alternatives or when not to use it, but the usage context is concrete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a document, a directory, or an entire folder. TWO CALLS, ALWAYS: the first returns what would be deleted and a confirm_token, and deletes NOTHING — show that to the person you are working for, get their answer, then call again with the token. Never confirm on their behalf. Requires OWNER on every file this would remove — including files you cannot see — and refuses the whole operation if even one is out of reach, rather than half-emptying anything. location names a file (deleted on its own) or a directory (everything beneath it). Pass a bare folder name to delete the WHOLE folder, which also removes its connector sync source and requires confirm_delete_folder. Sharing is NOT withdrawn: reach grants survive a delete, which is what lets undo_delete restore the folder with its sharing intact. History is content-addressed, so this is recoverable.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| location | Yes | full path from the workspace root, e.g. "handbook/vendor/acme.md" (as printed by list_org_docs or search_org_knowledge) | |
| confirm_token | No | OMIT on your first call — you get back what would be deleted, plus this token. SHOW THAT TO THE PERSON YOU ARE WORKING FOR and get their answer before calling again with it. | |
| confirm_delete_folder | No | required ONLY when deleting a whole folder: the folder's name again, exactly |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and succeeds: it discloses the two-call dry-run behavior, that the first call deletes nothing, the owner-permission requirement on every file including invisible ones, refusal instead of partial deletion, connector sync source removal, sharing persistence after deletion, and recoverability via content addressing.
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?
The description is dense but every sentence adds critical operational informationathe safety protocol is front-loaded, and details like sharing persistence and recoverability are concise yet complete. Structurally, key warnings are emphasized with capitalization and sentence-level separations that are easy to parse.
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?
Despite having no output schema and no annotations, the description covers what the tool deletes, how the confirmation flow works, permission requirements, folder-specific behavior, sharing implications, and recoverability. An agent has enough information to invoke it correctly and to communicate with the user before committing.
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%, but the description adds substantial semantic meaning beyond the schema: it clarifies that location can be a file or directory, that a bare folder name deletes the whole folder, that confirm_delete_folder is required only for whole-folder deletion, and that confirm_token must be omitted on the first call and presented to the user before the second call.
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?
The description opens with a specific verb and resource: 'Delete a document, a directory, or an entire folder.' It clearly defines the scope of deletion and distinguishes file-level vs. folder-level behavior, while also noting that history is content-addressed so the operation is recoverable — separating it from a permanent erase sibling.
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?
The description gives explicit usage protocol: 'TWO CALLS, ALWAYS,' show the first result to the person, get their answer, and never confirm on their behalf. It also explains when confirm_delete_folder is required. It does not explicitly contrast choice vs. erase_org_doc, but it references undo_delete as the restoration path, providing clear operational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change part of a document, leaving the rest untouched. Refuses rather than guessing: if the text you are replacing is missing, appears more than once without replace_all, the edit would remove the frontmatter block or leave it unparseable, or the document moved since expected_commit, nothing is written and you are told what is there now. If another writer commits between this call's read and its write, the edit is REFUSED rather than applied on top of theirs — re-read and re-apply. The confirmation carries a console link to the document you changed.
| Name | Required | Description | Default |
|---|---|---|---|
| node | No | the document's id, as returned beside its location — survives a rename or a move, so a citation written into a stored document keeps pointing at the right thing. Give this OR location, never both. | |
| share | No | the share id, when this location was shared with you from another workspace — list_org_folders prints it. Omit for your own folders. | |
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| location | No | full path from the workspace root, e.g. "handbook/vendor/acme.md". Give this OR node. A path is what a person reads; a node is what survives somebody reorganizing. | |
| new_string | Yes | what to put in its place | |
| old_string | Yes | exact text to replace — must appear in the current body | |
| replace_all | No | replace every occurrence (default: refuse if more than one) | |
| expected_commit | No | the document head you read at (read_org_doc prints it). Refuses if that document has moved since. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden, and it delivers extensively: refusal-over-guessing, five concrete refusal conditions, optimistic-concurrency refusal, recovery advice, and the console link in the confirmation. This is exemplary disclosure of failure behavior for 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and every sentence earns its place, covering purpose, refusal conditions, concurrency, and output in roughly 85 words. The second sentence is a dense run-on listing five refusal triggers, which slightly hurts readability.
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 complex 8-parameter mutation tool with no annotations and no output schema, the description covers the essential ground: scope, failure modes, concurrency behavior, remediation, and what the confirmation contains. It omits permission/authorization context, but the schema's token parameter partially covers that.
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% and the schema itself documents parameters well, giving baseline 3. The description adds genuine value by explaining the concurrency enforcement behind expected_commit and the multi-occurrence failure mode that motivates replace_all, going beyond the schema's one-line descriptions.
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?
"Change part of a document, leaving the rest untouched" names a specific verb and resource and the scope qualifier distinguishes it from the whole-document write_org_doc sibling. The front-loaded purpose makes the tool's role unambiguous even before reading the schema.
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?
The description gives clear behavioral rules (pass replace_all for repeated text, re-read and re-apply on stale expected_commit) but never explicitly says when to prefer this over write_org_doc or delete_org_doc. Usage context is implied rather than stated, with no exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PERMANENTLY destroy a document or a folder — its content, every past version, its comments and its name. NOTHING brings it back; this is not delete_org_doc, which is recoverable. Use it only for a genuine erasure request (someone asking that their data be removed), and prefer delete_org_doc for ordinary tidying. TWO CALLS, ALWAYS: the first returns exactly what would stop existing plus a confirm_token and destroys NOTHING — show that to the person you are working for, get their answer, then call again with the token. Never confirm on their behalf. Requires OWNER: what you own is erased and what you do not is left and reported, so a folder can come back partly done. The audit record of the erasure survives on purpose.
| Name | Required | Description | Default |
|---|---|---|---|
| node | No | the document's id, as returned beside its location — survives a rename or a move, so a citation written into a stored document keeps pointing at the right thing. Give this OR location, never both. | |
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| location | No | full path from the workspace root, e.g. "handbook/vendor/acme.md". Give this OR node. A path is what a person reads; a node is what survives somebody reorganizing. | |
| confirm_token | No | OMIT on your first call — you get back what would be destroyed, plus this token. SHOW THAT TO THE PERSON YOU ARE WORKING FOR and get their answer before calling again with it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the behavioral burden. It discloses permanent irreversibility, the two-call destroy-nothing-first protocol, partial behavior for folders when ownership is mixed, and the intentional survival of the audit record. It also warns against confirming on the user's behalf.
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?
Dense but every sentence earns its place; the most critical fact (permanent destruction) is front-loaded, and each subsequent sentence adds a distinct operational constraint. The emphasis through caps and the explicit two-call rule makes the high-risk behavior impossible to miss.
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 destructive two-step operation with no output schema, the description covers the first-call return (preview plus confirm_token), the second-call token requirement, ownership side effects, and audit retention. Nothing an agent needs to call this safely is missing.
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 description coverage is 100%, so the baseline is 3. The main description reinforces the two-call confirm_token workflow and node-versus-location distinction, but most parameter-level meaning already lives in the schema. It adds workflow context without substantially new parameter semantics.
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 precise verb ('destroy') and resource ('document or folder'), enumerates the full scope (content, versions, comments, name), and explicitly distinguishes itself from recoverable delete_org_doc. An agent can tell exactly what this tool does and how it differs from siblings.
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?
Explicitly says to use it only for genuine erasure requests, to prefer delete_org_doc for ordinary tidying, and never to confirm on behalf of the user. It also states the OWNER prerequisite. This is model guidance for when-to-use versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What YOU have been working on lately — documents you edited or opened, and which folders moved. Worth one call at the start of a session once you know what the user wants, to learn where in the store to look before you search. Returns observations only, never a claim about your role, and states what it is based on so you can tell a real picture from a thin one. A hint for aiming search_org_knowledge — not a substitute for it.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | how far back to look, in days (default 30) | |
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it delivers: 'Returns observations only, never a claim about your role, and states what it is based on so you can tell a real picture from a thin one.' This communicates read-only, evidence-based behavior and even warns the agent about how to judge the reliability of what it receives.
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?
Four sentences, each adding a distinct point: scope, timing, behavior, and relationship to a sibling tool. Slightly verbose phrasing like 'so you can tell a real picture from a thin one' makes it less than maximally tight, but there is no wasted filler.
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 simple two-optional-param tool with no output schema, the description covers purpose, when to call, what it returns, and how to judge the result. It does not specify exact output formatting or ordering, but the agent has enough context to call it and interpret its role.
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 description coverage is 100%, so the schema already documents the two optional parameters. The description adds context around what 'recent' refers to but does not add new parameter-level meaning, landing at the baseline 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?
The description opens with a concrete picture of the tool's resource — 'documents you edited or opened, and which folders moved' — and later clarifies that it 'returns observations only.' It explicitly contrasts itself with search_org_knowledge, so an agent can distinguish the two without opening schemas.
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?
It gives an explicit trigger and purpose: 'Worth one call at the start of a session once you know what the user wants, to learn where in the store to look before you search.' It also states a clear boundary: 'A hint for aiming search_org_knowledge — not a substitute for it.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the documents you are authorized to read in a folder. Use this to browse; use search_org_knowledge to answer a question. Filtering by label matches labels INHERITED from a folder or directory as well as a document's own, so a folder's label returns everything inside it.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | deprecated alias for `label` | |
| type | No | only documents of this type (meeting-notes, playbook, spec, brand-asset, web-clip, contract, misc); set it with frontmatter on write | |
| label | No | label to filter by — matches a document's own labels AND any inherited from a folder or directory above it. Organization only; labels never affect what you are allowed to read | |
| limit | No | max results this page (clamped to the server cap MAX_PAGE_SIZE) | |
| share | No | the share id, when this location was shared with you from another workspace — list_org_folders prints it. Omit for your own folders. | |
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| offset | No | results to skip — pass the previous page's nextOffset to page | |
| location | Yes | full path from the workspace root, e.g. "handbook/vendor/acme.md" (as printed by list_org_docs or search_org_knowledge) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the authorization scope ('documents you are authorized to read') and the non-obvious inherited-label matching behavior. It stops short of stating the return shape or confirming non-mutation, but 'list' and 'browse' make the read-only nature clear.
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?
Three short sentences: purpose, usage routing, and one subtle filtering behavior. No fluff, and the most important info is front-loaded.
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 list tool with an eight-parameter schema that is fully self-describing, the description plus schema covers what is needed to call it. A note on the exact return fields or output shape would be the only meaningful addition, given there is no output schema.
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 the baseline is 3. The description's label sentence largely restates the schema's label property, so it adds little incremental parameter meaning; other parameters are already fully described in the schema.
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?
Opens with a specific verb and object: 'List the documents you are authorized to read in a folder.' It also distinguishes the tool from search_org_knowledge by framing it as browsing, so an agent can tell them apart immediately.
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?
Explicitly instructs when to use: 'Use this to browse; use search_org_knowledge to answer a question.' This names the alternative and the deciding condition with no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Orientation call, worth making once at the start of any session about this organization: lists the folders you can reach and what is in them. Pass a folder to see its shape — how many files you can read, by type and label, and how many are gated from you. Labels include ones inherited from the folder, so they name what a folder is about, not only what individual documents declare.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| parent | No | list inside this folder, e.g. "handbook" or "handbook/vendor". Omit for the top level. | |
| location | No | full path to scope to, e.g. "handbook" or "handbook/vendor". Omit to cover everything you can reach. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses output behavior: counts of readable files by type and label, gated counts, and inherited labels. It doesn't explicitly state the tool is read-only, but 'lists' implies non-mutating. The inherited-label nuance adds useful behavioral context beyond the schema.
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?
Three sentences, each earning its place. The first front-loads purpose and usage, the second details output shape, and the third explains label inheritance. No redundant or filler content.
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 simple listing tool with no output schema, the description covers purpose, usage, and behavior well. It explains what the return value will include (folders, counts, gating). A minor gap is not explicitly mentioning the token parameter, but the schema fully handles that, and the tool is straightforward.
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 description coverage is 100%, so the baseline is 3. The description references 'Pass a folder' which maps to parent/location, but it doesn't add meaning beyond what the schema already documents. The schema descriptions for parent and location are self-explanatory.
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?
The description uses a specific verb and resource: 'lists the folders you can reach and what is in them.' It clearly differentiates from siblings like list_org_docs (documents) and list_org_sources (sources) by focusing on folders. The purpose is unmistakable.
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?
Explicitly tells when to use it: 'worth making once at the start of any session about this organization.' It also explains when to pass a folder ('Pass a folder to see its shape'). It doesn't name alternative tools, but the orientation context strongly implies the appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who is in this organization and what groups exist, with each group's membership. Use it before granting access, so 'the team' resolves to actual people instead of a guess. Pass a group to see just its members. Names people and groups only — never anybody's content.
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | a group id or its exact name, to list just that group's members | |
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool is read-only in nature (listing names and groups, never content), which implies a safe, non-destructive operation. It also discloses the scope limitation (no content access) and the optional filtering behavior. It doesn't mention pagination or rate limits, but for a simple listing tool the behavioral context is reasonably complete.
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?
The description is compact and front-loaded with the core purpose. Every sentence earns its place: the first states what it does, the second gives usage context, the third explains the optional parameter, and the fourth sets expectations about output scope. No wasted words.
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 simple listing tool with no output schema and no annotations, the description covers the essential context: what it returns (people and groups), how to filter (by group), when to use it (before granting access), and what it excludes (content). It doesn't describe the exact return format or pagination, but those are minor gaps for this tool's simplicity.
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 description coverage is 100%, so the schema already documents both parameters. The description adds value by explaining the purpose of the group parameter ('to list just that group's members') and the token override semantics ('Usually omitted — supplied by the transport'). This goes beyond the schema's basic descriptions and helps an agent understand when to pass each parameter.
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?
The description clearly states the tool's function: listing people in the organization and groups with their memberships. It uses a specific verb ('list') and resource ('org people and groups'), and distinguishes itself from siblings like list_org_docs and list_org_folders by explicitly scoping to people and groups only.
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?
The description provides explicit guidance on when to use this tool: 'Use it before granting access, so 'the team' resolves to actual people instead of a guess.' It also explains the optional group parameter usage ('Pass a group to see just its members') and clarifies what the tool does not return ('never anybody's content'), which helps an agent avoid using it for content-related queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What this organization has connected — GitHub repositories, Google Drive folders — where each one writes, and whether it is actually syncing. Call it after connecting something to confirm it worked, or when content you expected is missing and you want to know whether the source ran and failed or never ran at all. Sync is ONE-WAY, from the source into agentleFS, and it repeats: the source is polled and the destination folder is brought up to date. Documents you write here are not pushed back to the repository, and a connector-owned path refuses direct edits rather than having them silently overwritten on the next run.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. |
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 thoroughly. It discloses that sync is one-way, polling-based, and repeats, that written documents are not pushed back, and that connector-owned paths refuse direct edits. This gives the agent an accurate mental model of the underlying behavior beyond the bare listing function.
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?
The description is compact and front-loaded with purpose and usage, then adds behavioral nuance. Each sentence contributes meaning, though the sync semantics section is slightly detailed for a listing tool. Still, that detail justifies its place given the lack of annotations and output schema.
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 zero-required-parameter read-style tool with no output schema, the description is complete: it explains what is listed, when to call it, how to interpret the results ('ran and failed or never ran'), and the behavioral constraints around sync. Nothing essential is missing.
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?
The only parameter is 'token' and its schema description already fully explains its purpose and when to pass it (100% schema coverage). The description adds no parameter-specific semantics, but the baseline of 3 applies because the schema already does the work.
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?
The description clearly identifies the resource ('what this organization has connected'), the action (listing connected sources), and the key returned aspects (destination, sync status). It also distinguishes itself from siblings by explicitly tying the listing to post-connection verification, separating it from connect_org_source or add_org_source.
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 explicit, actionable use cases: 'Call it after connecting something to confirm it worked' and 'when content you expected is missing... whether the source ran and failed or never ran at all.' This tells an agent exactly when to select this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add to the board on a folder or document, for whoever reads it next. kind=context leaves a note (why something is shaped the way it is, what not to change). kind=request asks for something, optionally naming people or agents in to (an email, or the exact name list_org_people prints) — naming someone shares NOTHING with them: they see it only if they can already read this. kind=inconsistency flags that this disagrees with another folder or document, named in about. kind=working says you are in the middle of something here so nobody duplicates it; it expires on its own (72h unless expires_in_hours). To reply to a post, pass reply_to with its id (a reply's id works: it joins that thread); add close=closed with your reason as the body to close it, or close=refused to decline a request addressed to you. Posts are attributed to you and marked as coming from an agent. Board posts are never search-ranked; they show beside what readers open.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | request only: up to 20 people or agents — an email, or a name exactly as list_org_people prints it | |
| body | No | what you are saying. One short paragraph; link a document for anything longer. | |
| kind | No | context | request | inconsistency | working — required unless replying | |
| node | No | the folder's or document's id. Give this OR location. | |
| about | No | inconsistency only: the OTHER folder or document, by path or id | |
| close | No | with reply_to: close the thread, or refuse a request asked of you | |
| share | No | the share id, when this location was shared with you from another workspace — list_org_folders prints it. Omit for your own folders. | |
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| location | No | the folder or document to post on. Give this OR node (not needed with reply_to). | |
| reply_to | No | a post id (or its 8-character prefix) to reply to instead of starting a thread | |
| scope_type | No | only when a path names both a folder and a document | |
| about_scope_type | No | only when `about` names both a folder and a document | |
| expires_in_hours | No | working only: how long the claim lasts |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it discloses high-risk behaviors explicitly: posting is attributed to the agent, shares nothing with named recipients beyond existing read access, working posts expire on their own, and board posts are excluded from search ranking. It also explains that a reply's id joins the original thread and that close=refused declines a request. This goes beyond the schema's enum names and gives the agent expectations for side effects like attribution and expiry.
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?
The description is dense and front-loaded with the core action, and every sentence carries information. However, it is a long single block of text without paragraph breaks or bullet structure, which makes it harder to scan for an agent deciding among kind values. The length is justified by the complexity, but the structure could be improved with visual separation of the four kinds.
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 complex 13-parameter tool with no output schema and no annotations, the description covers the purpose, all four kinds, threading semantics, closing semantics, sharing semantics, attribution, expiry, and search behavior. It also references sibling tools list_org_people and list_org_folders to resolve ambiguities about names and share ids. Nothing essential for correct invocation is missing.
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 description coverage is 100%, so the baseline is 3 and the description needs only to add value beyond the schema's param docs. The description does add semantic nuance, e.g., reply_to accepts an 8-character prefix, close pairs with reply_to, and expires_in_hours is for working claims. However, most parameters are already well described in the schema, so the added value is moderate rather than transformative.
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?
The description opens with a concrete verb and resource — 'Add to the board on a folder or document' — and then elaborates the four kinds of posts and their distinct intents (context, request, inconsistency, working). This distinguishes post_org_board from all siblings, especially read_org_board, because the description positions it as the writing counterpart, while the schema and sibling list make the pairing apparent. The enumeration of kinds adds purpose clarity beyond a generic 'post something' statement.
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?
The description gives explicit when-to-use guidance for each mode: when to use kind=context, kind=request, kind=inconsistency, kind=working, and when to use reply_to instead of starting a thread. It also explains when close=closed vs close=refused applies, and when to pass expires_in_hours. This is richer conditional guidance than most tool descriptions, and it routes the agent away from overuse by saying 'naming someone shares NOTHING with them' and 'Posts are never search-ranked'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the board on a folder or document: context people and agents left for whoever reads next, open requests and who they are for, inconsistencies flagged between two documents, and who is working on what. A document's board includes what it inherits from the folders above it; a folder's includes what is open below it and who has been editing nearby. Pass post to read one thread in full (a reply's id works too). Pass no location, node or post to see every request waiting on you, everywhere you can read — or requests="asked_by_me" for the ones YOU asked that are still open. A board is paged: the footer says how many there are and the offset for the next page. read_org_doc, list_org_docs and the write tools already show a short board trailer — call this when you want the whole of it.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | with a location or node: only posts of this kind | |
| node | No | a folder's or document's id. Give this OR location. | |
| post | No | a post or reply id, or the 8-character prefix printed beside it, to read that thread in full | |
| limit | No | posts per page (default 25) | |
| share | No | the share id, when this location was shared with you from another workspace — list_org_folders prints it. Omit for your own folders. | |
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| offset | No | posts to skip — the footer of the previous page names it | |
| status | No | with a location or node: default open | |
| location | No | a folder or document path, e.g. "product" or "product/pricing.md". Give this OR node. | |
| requests | No | with no location or node: requests waiting on you (default), or requests you asked that are still open | |
| scope_type | No | only when a path names both a folder and a document |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses paging behavior (footer shows count and offset), threading via post id, and inheritance semantics. It doesn't explicitly state it's non-mutating, but the verb 'read' implies that, and no side effects are mentioned. For a read operation, this is adequate transparency; a 4 reflects that it goes beyond the schema but doesn't explicitly address non-mutation.
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?
The description is a single dense paragraph, but every clause earns its place given the 11-parameter complexity. It front-loads the core purpose and then layers usage modes and paging details. While long, it's efficiently structured; a 4 reflects that it could benefit from bullet points but remains readable and non-redundant.
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 tool with 11 parameters and multiple modes, the description covers all necessary operational aspects: what a board contains, inheritance rules, paging, thread reading, global request views, share handling, and token override. Even without an output schema, it describes the footer and the kinds of posts returned. Nothing an agent needs to call it correctly is missing.
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%, but the description adds significant semantic value: it explains how parameters interact (e.g., 'Pass post to read one thread in full'), when to omit them (global requests), and how offset relates to the footer. It also clarifies the 'requests' enum and share context. This goes far beyond the schema's one-line definitions, making the tool genuinely easier to use correctly.
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?
The description opens with a clear verb and resource ('Read the board on a folder or document') and enumerates the specific content types (context, requests, inconsistencies, working). It also distinguishes itself from sibling read tools by noting that other tools show only a short trailer, positioning this as the full-board reader. This differentiates it effectively.
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?
The description gives explicit guidance on when to use this tool vs alternatives: 'read_org_doc, list_org_docs and the write tools already show a short board trailer — call this when you want the whole of it.' It also explains multiple usage modes (post to read a thread, no arguments for global requests, requests='asked_by_me' for own requests) with clear conditions. No ambiguity about when to invoke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open one document and read it. Returns a shareable console link alongside the body so you can cite what you used. A path you cannot read returns not-found — identical to a path that does not exist, so this never reveals that a file you are denied exists.
| Name | Required | Description | Default |
|---|---|---|---|
| node | No | the document's id, as returned beside its location — survives a rename or a move, so a citation written into a stored document keeps pointing at the right thing. Give this OR location, never both. | |
| share | No | the share id, when this location was shared with you from another workspace — list_org_folders prints it. Omit for your own folders. | |
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| offset | No | byte offset to start at (page large files) | |
| location | No | full path from the workspace root, e.g. "handbook/vendor/acme.md". Give this OR node. A path is what a person reads; a node is what survives somebody reorganizing. | |
| maxBytes | No | max bytes to return (clamped to MAX_READ_BYTES) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does well by disclosing two meaningful behaviors: it returns a shareable console link alongside the body, and it returns not-found for denied paths to avoid revealing file existence. It does not mention pagination or error semantics beyond that, but the core transparency is strong.
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?
The description is three sentences with no wasted words. It leads with the action, then the return value, then an important privacy behavior, all in a compact and readable structure.
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?
Given there is no output schema, the description explains the core return value: a shareable console link and the document body. It also covers the privacy-sensitive not-found behavior. It does not describe how offset/maxBytes affect output, but the schema explains those parameters, so the description is largely complete for an agent to invoke the tool correctly.
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 description coverage is 100%, so the parameters are already well-documented. The description adds little beyond the schema, except context about path vs. node semantics and the not-found behavior, but it does not need to compensate since the schema covers all six parameters.
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?
The description uses a specific verb and resource: 'Open one document and read it.' It clearly signals a single-document read operation, distinguishing it from list, search, write, and edit siblings by focusing on retrieval of an existing document's body and a console link.
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?
The description clearly implies this tool is for reading one document, which is a clear usage context. It does not explicitly name alternatives or when not to use it, but the read-specific language and mention of node/location paths make the intended use evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retire (revoke) an agent you added, and every agent it added in turn: their access and tokens are revoked, and this cannot be undone. Call with no agent to list the agents you added that are still live. TWO CALLS to retire: the first previews who would be retired and returns a confirm_token.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | No | the agent's id, as add_org_agent or the listing printed it. Omit to list yours | |
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| confirm_token | No | from the first call. Calling with an agent but without it PREVIEWS: nothing is retired. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for disclosing behavior, and it does so thoroughly: it states that access and tokens are revoked, that revocation cannot be undone, that the operation cascades to child agents, and that the first call only previews and returns a confirm_token.
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?
The description is compact and front-loaded, with every sentence earning its place: the core action and consequences come first, followed by listing mode and the two-call workflow. No filler or repetition.
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?
The description covers the critical aspects: what is revoked, irreversibility, cascading behavior, listing mode, and the preview/confirm mechanism. It does not describe the final response after a successful confirmation call, and there is no output schema to fill that gap, but the essential calling contract is clear.
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 description coverage is 100%, so the baseline is 3; the schema already explains agent, token, and confirm_token. The description adds useful workflow context around the two-call pattern, but most parameter meaning is already present in the input schema, so no higher score is warranted.
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?
The description clearly identifies the action ('Retire (revoke) an agent you added'), the resource (an agent), and the cascading effect on every agent it added. It also distinguishes listing mode from revocation mode, making its purpose unambiguous relative to siblings like revoke_org_share.
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?
The description gives explicit usage context: call with no agent to list live agents, and use the two-call flow to preview then confirm revocation. It does not explicitly name sibling alternatives or state when not to use this tool, but the guidance is clear enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search what this organization has written down — policies, runbooks, decisions, postmortems, onboarding docs, past projects. ACL-filtered to you: content you lack a role for is never returned. Omit folder to search everything you can reach.
| Name | Required | Description | Default |
|---|---|---|---|
| how | No | auto (default) searches by meaning where available and falls back to text; meaning = semantic; text = exact string; titles = file metadata only | |
| limit | No | max results this page (clamped to the server cap MAX_PAGE_SIZE) | |
| query | Yes | what you want to know, in the user's own words | |
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| offset | No | results to skip — pass the previous page's nextOffset to page | |
| location | No | full path to scope to, e.g. "handbook" or "handbook/vendor". Omit to cover everything you can reach. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral disclosure burden. It discloses a key non-obvious behavior: results are ACL-filtered so content the user lacks a role for is never returned. It also implies a read-only search operation and explains scope behavior. It does not describe result shape or pagination behavior, but the most important hidden behavior is covered.
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?
The description is compact at three sentences and front-loaded with purpose, followed by a key behavioral note and a scope usage tip. It has almost no waste, but the misleading backticked 'folder' reference costs a point against an otherwise clean structure.
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?
The description covers the most important non-obvious aspects: what content is searched, the ACL filtering behavior, and how to expand scope. However, with no output schema and six parameters, it gives no indication of the return shape, result ordering, or how matches are presented, and the folder/location ambiguity is a real gap. It is adequate but not fully complete.
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 description coverage is 100%, so the baseline is 3. The description adds high-level context about content types and the scope-widening behavior, but it does not add per-parameter detail beyond the schema. Its use of 'folder' where the schema has 'location' muddles rather than enhances the schema's already clear parameter documentation.
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?
The description opens with the verb 'Search' and clearly identifies the resource: organizational written knowledge, enumerating representative content types like policies, runbooks, decisions, and postmortems. This distinguishes it from siblings such as read_org_doc or list_org_docs, even though it does not name them explicitly. The minor 'folder' vs 'location' wording does not obscure the tool's overall purpose.
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?
It provides clear context for when to use the tool: when looking for information the organization has written down, with a notable ACL-filtering constraint. It also gives an explicit usage tip, 'omit folder to search everything you can reach.' However, it does not state exclusions or point to alternatives like list_org_docs for directory-style browsing, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Undo the last delete at a location — a document, a directory, or a whole folder. Restores exactly what that one delete removed, at the version it had, with its sharing intact. Pass the same location that was deleted. Undoing twice is harmless: the second call finds nothing left to restore and says so. A document that was deleted before it ever had content cannot be restored and is reported separately rather than resurrected empty.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| location | Yes | full path from the workspace root, e.g. "handbook/vendor/acme.md" (as printed by list_org_docs or search_org_knowledge) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It transparently covers idempotency, restoration of the prior version, preservation of sharing, and the cannot-restore-empty-document edge case. It does not address permission requirements or conflicts with existing items at the target location, but the major behaviors are disclosed.
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?
The description is composed of four focused, front-loaded sentences. Each sentence earns its place, with edge cases stated efficiently rather than padded.
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?
The tool is simple (one required parameter, no nested objects), and the description covers scope, idempotency, and a notable failure case. It does not detail the exact return payload, and there is no output schema to compensate, but it gives enough for an agent to invoke the tool correctly in most situations.
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?
The schema already provides 100% description coverage for both parameters, so the baseline is 3. The description adds the useful directive to pass the same deleted location and clarifies that location can be a document, directory, or folder, but largely reinforces rather than extends the schema.
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?
The description states a specific verb ('Undo') and a specific resource ('the last delete at a location'), and enumerates the kinds of locations accepted: document, directory, or folder. This clearly distinguishes it from deletion-oriented siblings such as delete_org_doc and erase_org_doc.
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?
It provides clear guidance on when to use the tool: after a delete, pass the same `location` that was deleted. It also reassures the agent about repeated calls ('Undoing twice is harmless'). It does not explicitly name the delete tool it reverses or state when not to use it, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Who currently reaches a folder or document — people and groups inside this organization, direct and inherited, AND people outside it who hold a share. Call it after sharing to confirm the grant landed, or before sharing to see who is already there. Names people, never their content. Answers only for a scope you reach yourself; one you do not answers not-found, identical to a scope that does not exist.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| location | Yes | full path from the workspace root, e.g. "handbook/vendor/acme.md" (as printed by list_org_docs or search_org_knowledge) | |
| scope_type | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses important behavior: it names people/group access, never content, and it returns not-found for scopes the caller cannot reach, making that indistinguishable from a nonexistent scope. It does not explicitly state that the operation is read-only or describe how the response is structured, but the key security-relevant behaviors are covered.
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?
Four sentences, each earning its place: purpose, usage timing, return scope, and error/visibility behavior. The most important information is front-loaded and there is no redundant or promotional wording.
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?
Given the absence of an output schema and annotations, the description covers the essential points: what is returned, when to call it, and how inaccessible scopes are handled. It does not specify the exact output shape or how direct versus inherited access is represented, but this is a minor gap for a tool whose core semantics are otherwise clearly described.
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?
The input schema already documents location with an example, token override semantics, and the scope_type enum, covering about 67% of parameters meaningfully. The description adds a conceptual folder/document framing that aligns with scope_type, but it does not add detail beyond the schema, which is adequate but not exceptional.
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?
The description states exactly what the tool does: it identifies who can currently reach a specific folder or document, covering internal people/groups with direct or inherited access and external holders of shares. It also distinguishes itself from siblings like list_org_people by scoping to a specific location and returning access relationships rather than directory membership.
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?
The description gives explicit use cases: call after sharing to confirm the grant landed, or before sharing to see who is already there. It does not name alternative tools or state when not to use it, but the provided context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Persist something durable — a resolved answer, a runbook, a decision — so the next agent inherits it. Ephemeral chat output is lost. Commits immediately if your grant allows it, and is refused if it does not. The confirmation says whether it CREATED the document or OVERWROTE one, names any directory that did not exist before (check it against what you meant — a typo in folder_path silently mints a new one), and carries a console link you can hand to a person. Set metadata with YAML frontmatter at the top of content: type (one of: meeting-notes, playbook, spec, brand-asset, web-clip, contract, misc — anything else becomes misc), title, summary, and tags as a list. tags is the write-side spelling of what the listing tools call label. status takes active or inactive and is not a label: inactive retires a document — it stays in the folder and stays openable in the console, but agents stop retrieving it. Omit it unless you mean to retire something.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | the document name, e.g. "Q3 summary.md". Cannot contain "/" — put folders in folder_path instead. END IT IN .md unless you mean otherwise: only .md and .mdx render in the console, and anything else opens as plain text with no way to switch. Nothing is appended for you. | |
| share | No | the share id, when this location was shared with you from another workspace — list_org_folders prints it. Omit for your own folders. | |
| token | No | Bearer token identifying the principal. Usually omitted — supplied by the transport (HTTP Authorization header or the server's AGENTLEFS_TOKEN env). Only pass this to override. | |
| content | Yes | ||
| folder_path | Yes | folder names, outermost first, e.g. ["handbook","policies"] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses immediate commitment or refusal based on the grant, the created-vs-overwritten confirmation detail, the silent creation of new directories from folder_path typos, and the exact retirement semantics of inactive status. This is exceptionally transparent about side effects.
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?
The description front-loads the core purpose in the first sentence and then packs commit behavior, confirmation semantics, metadata rules, and status meaning into dense, operationally relevant sentences. There is no filler or repetition.
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 write tool with no output schema and no annotations, the description covers purpose, permission refusal, side effects, confirmation response contents, and metadata options. An agent has enough information to invoke it safely and correctly.
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?
The schema already documents name, share, token, and folder_path, and the description adds the otherwise-missing meaning of content via YAML frontmatter, type mapping, tags/label relationship, and status behavior. It also adds a valuable warning about folder_path typos. It does not revisit every parameter, but it goes beyond the baseline.
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?
The description opens with a specific action, 'Persist something durable,' and identifies the resource as an organization document that later agents inherit. It also clarifies that the operation either CREATES or OVERWRITES a document, which positions it clearly against siblings like edit_org_doc, delete_org_doc, and read_org_doc.
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?
It gives a clear context for use: persist answers, runbooks, or decisions so they outlive ephemeral chat output, and it explains when to omit or include status. It does not explicitly name sibling alternatives or state when not to use the tool, so it stops short of full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
add_org_agentadd_org_sourceclaim_share_linkconnect_org_sourcecreate_org_foldercreate_org_share_linkdelete_org_docedit_org_docerase_org_doclist_my_recent_worklist_org_docslist_org_folderslist_org_peoplelist_org_sourcespost_org_boardread_org_boardread_org_docrevoke_org_agentrevoke_org_sharesearch_org_knowledgeshare_org_folderundo_deletewho_can_readwrite_org_docShared company knowledge, workflows, and connected apps for the AIs your team already uses.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
Add one secure layer between your agents and this server.
