AI-first file sharing and collaboration. 251 tools give agents a full workspace: file storage, branded shares, comments, workflows, and built-in RAG. 50GB free, no credit card.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.3/5 across 19 of 19 tools scored. Lowest: 3.5/5.
Each tool covers a clearly distinct domain (auth, storage, shares, comments, events, AI, etc.), and overlapping concepts like share vs. fileshare are explicitly disambiguated with deprecation notes and cross-references. An agent can reliably select the correct tool for a task without ambiguity.
Tool names are all lowercase single words, but they mix nouns (user, org, workspace) with verbs (download, find, upload) and include a hyphenated 'how-to'. There is no consistent verb_noun or noun-only pattern, though the names are still readable and memorable.
19 tools is slightly above the typical 3-15 sweet spot, but the platform's breadth (auth, file management, sharing, collaboration, AI, metadata, and help) justifies this count. Each tool represents a substantial domain area, so none feel redundant.
The toolset provides full lifecycle coverage for the platform: authentication, user/org/workspace management, file storage/upload/download/search, sharing (both quickshare and durable file shares), comments, events, metadata pipelines, AI assistance, and product help. No obvious dead ends or missing operations are apparent.
aiARipley — the MCP delegation surface over Fastio's RAG agent. Ripley is read-only for storage CONTENT: it answers natural-language questions about workspace/share files & folders (with citations) and never creates/edits/deletes your files — for content writes, call the primitive MCP tools directly. It DOES create/manage chat threads (chat-create/chat-update/chat-delete/message-send) and can generate shares (share-generate). Prefer Ripley over issuing many primitive reads: ask one NL question and let the server-side agent search + synthesize. Quick start: action='ask' (question + profile) → returns {answer_text, citations, chat_id, message_id, web_url}; action='status' for an engineered workspace-status summary. Lower-level chat/message actions remain for multi-turn control. Call action='describe' for the full action/param reference. Destructive: chat-delete. Side effects: ask/status/chat-create/message-send consume credits; chat-cancel terminates an in-progress message (partial tokens billed; idempotent). Verbosity (detail param): chat-list/message-list default to terse (compact rows). chat-details/message-details default to full (drill-down). Pass an explicit detail='standard'|'full' to override (best-effort: chat/message/activity endpoints may not yet honor detail server-side).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | chat-create (workspace only): 'user' (default) or 'agent' — flags the chat as agentic; set at creation, immutable; not accepted on share chats. chat-list: filter by 'user'|'agent'|'all'. | |
| name | No | New chat name. | |
| wait | No | message-read only. Default true: bounded-wait for completion (up to ~24s on a workspace via the activity long-poll). Set false for a single-shot status probe (one details fetch, ~1 round-trip) — useful against strict ~30s client timeouts. | |
| files | No | File opaque IDs (max 25, share share-generate). | |
| limit | No | chat-list/message-list page size. Best-effort: the AI API spec documents NO pagination on the chat-list or message-list endpoints (both return all rows under {count, items}), so this is forwarded but may be a silent no-op until the platform adds paging. | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| detail | No | Per-entity verbosity for chat-list/chat-details/message-list/message-details (best-effort: chat/message/activity endpoints may not yet honor detail server-side). Defaults: terse for list-style (chat-list, message-list), full for details (chat-details, message-details). See action='describe' for per-level field lists. | |
| offset | No | chat-list/message-list pagination offset — see the limit caveat (no documented paging on these endpoints; forwarded best-effort). | |
| chat_id | No | AI chat ID. | |
| privacy | No | Chat privacy (default: private). Workspace chat-create only — share chats are always private. | |
| node_ids | No | File node IDs (max 25, workspace share-generate). | |
| share_id | No | Alias for profile_id when the profile is a share — implies profile_type=share (so profile_type may be omitted). | |
| context_id | No | Alias for profile_id (either name works) | |
| message_id | No | AI message ID. | |
| profile_id | No | Polymorphic context ID (pair with profile_type=workspace|share). Typed aliases let you omit profile_type: workspace_id (⇒ workspace) / share_id (⇒ share); also context_id / instance_id. 19-digit workspace or share ID. | |
| query_text | No | Question or prompt (max 32,000 chars). | |
| instance_id | No | Alias for profile_id (REST/how-to name; profile_id is canonical). | |
| context_type | No | Alias for profile_type (either name works) | |
| files_attach | No | Attach workspace FILES for the AI to read directly (comma-separated nodeId:versionId pairs; versionId optional → backend resolves current). Works regardless of workspace intelligence. A missing/inaccessible/ineligible node ERRORS (not a silent drop). See describe. | |
| profile_type | No | Profile type: "workspace" or "share". | |
| workspace_id | No | Alias for profile_id when the profile is a workspace — implies profile_type=workspace (so profile_type may be omitted). | |
| folders_attach | No | Attach workspace FOLDERS for the AI to read (comma-separated folder nodeIds; no depth). Denied on restricted-view shares. See describe. | |
| include_deleted | No | chat-list: if true, list deleted chats via the /deleted variant (workspace AND share). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=true), the description details that storage content is read-only, but chat threads and shares are created, and specifically names 'Destructive: chat-delete'. It further discloses credit consumption for certain actions, idempotency of chat-cancel, and best-effort behavior of detail/pagination parameters — no contradiction.
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?
Although long, every sentence carries actionable information: purpose, usage preference, write caveat, quick start, side effects, destructive actions, and verbosity defaults. The structure is front-loaded and logically organized, making the length appropriate for a 23-parameter multi-action tool.
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 is exceptionally complete for a complex tool with no output schema. It covers the core workflows (ask, status, chat management, share generation), return shape for ask, side effects (credits, cancellation), and edge cases like the wait parameter and best-effort detail/pagination. Combined with the rich schema, an agent has all necessary context to invoke 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 input schema already covers all 23 parameters (100% coverage), so baseline is 3, but the description adds meaning beyond the schema: it highlights the 'ask' quick start with its return shape, 'status' and 'describe' actions, and explains default verbosity for list vs details actions. It also clarifies that 'limit' and 'offset' may silently be no-ops.
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 tool as 'the MCP delegation surface over Fastio's RAG agent' with a specific verb: 'answers natural-language questions about workspace/share files & folders (with citations)'. It also distinguishes itself from siblings by stating it never creates/edits/deletes files and that content writes should use primitive MCP tools directly, plus it manages chat threads and shares.
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?
Explicit guidance is given: 'Prefer Ripley over issuing many primitive reads: ask one NL question' and 'for content writes, call the primitive MCP tools directly' — a clear when-to-use and when-not-to-use. It also notes lower-level chat/message actions for multi-turn control and points to 'describe' for full reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
assetABrand asset management (logos, banners, profile photos) on org/workspace/share/user. Upload, delete, list, read. Call action='describe' for the full action/param reference. Destructive: delete.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Operation. Use 'describe' for full action reference. | |
| content | No | Plain text content (e.g. SVG). | |
| asset_id | No | Asset ID or name. | |
| metadata | No | Additional metadata as JSON array string. | |
| entity_id | No | Opaque ID of a specific object (file, comment, etc.). Pair with entity_type to disambiguate. Entity ID (optional for user). | |
| file_name | No | Original file name. | |
| asset_type | No | Asset type key (e.g. 'logo', 'banner', 'photo'). | |
| entity_type | No | Entity type. | |
| file_base64 | No | Base64-encoded binary content. | |
| content_type | No | MIME type (default application/octet-stream). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint=true, and the description explicitly calls out 'Destructive: delete', adding specificity beyond the annotation. It also discloses the range of actions. No contradiction with annotations (readOnlyHint=false, destructiveHint=true).
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 purpose, followed by operational scope and a clear pointer to the describe action. Every sentence earns its place with no redundancy.
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 has 10 parameters and no output schema, but the schema itself is richly described. The description covers the main actions and explicitly defers to action='describe' for full details. Minor gap: the 'types' action is not mentioned, but the pointer to describe mitigates this.
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 has 100% description coverage, so all parameters are already documented in the schema. The tool description does not add parameter-level meaning beyond the schema, but it does provide domain context (e.g., logos, banners, profile photos). 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?
Description states a specific verb+resource: 'Brand asset management' with concrete asset types (logos, banners, profile photos) and scope (org/workspace/share/user). It lists key operations (upload, delete, list, read) and distinguishes itself from generic sibling tools like upload/download by naming the asset domain.
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?
Provides clear context on what the tool manages and its entity scope. Points users to action='describe' for the full action/param reference, which is useful meta-guidance. However, it does not explicitly state when to use this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
authAAuth & sessions: signin, signup, signout, 2FA, PKCE, API keys, OAuth sessions. Call action='describe' for the full action/param reference. Destructive: api-key-delete, oauth-revoke, oauth-revoke-all.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Verification or authorization code. Meaning is action-specific — see action='describe' for the per-action reference (e.g. 2FA code for 2fa-verify, reset code for password-reset, OAuth code for pkce-complete). | |
| name | No | API key label. | |
| No | Email address. | ||
| token | No | 2FA / verification token. Meaning is action-specific — see action='describe' for the per-action reference (e.g. 2FA-disable token, 2fa-verify-setup token, 2FA token for api-key-create/api-key-delete). | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| key_id | No | API key identifier. | |
| scopes | No | Scope strings, e.g. ['org:123:rw']. Omit for full access. | |
| api_key | No | Fastio API key. | |
| channel | No | 2FA channel. | |
| expires | No | Token lifetime in seconds. | |
| password | No | Account password. | |
| last_name | No | Family name. | |
| password1 | No | New password. | |
| password2 | No | New password confirmation. | |
| agent_name | No | Agent name for approval screen and audit logs. | |
| first_name | No | Given name. | |
| scope_type | No | PKCE scope type. Default 'user' (full access). | |
| session_id | No | OAuth session identifier. | |
| email_token | No | Email verification code. | |
| key_expires | No | ISO 8601 expiration datetime. | |
| describe_action | No | When action='describe', narrow the output to ONE action's full params/notes (e.g. 'status'). Omit to get the compact action index. | |
| exclude_current | No | Skip current session in revoke-all. | |
| current_session_id | No | Current session ID for exclusion. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already show readOnlyHint=false and destructiveHint=true, and the description adds value by listing the specific destructive actions. It also discloses that the tool manages sessions and auth flows. It does not detail side effects like email/SMS sending or session creation, but the action names and describe reference reduce the need.
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 front-load the tool's scope, then point to the describe action, then list destructive operations. Every sentence earns its place with 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?
Given the high complexity (29 actions, 23 params) and no output schema, the description compensates by directing the agent to the built-in describe mechanism. It also names destructive actions as a safety hedge. It is not exhaustive about return values or side effects, but the self-discovery path makes it sufficiently 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 itself adds minimal parameter-level detail. It only mentions that action='describe' provides the per-action reference. The schema already explains action-specific meanings of 'code' and 'token', so the description adds little beyond that.
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 tool as covering 'Auth & sessions' and enumerates major categories (signin, signup, 2FA, PKCE, API keys, OAuth). It is distinct from sibling tools like 'user' or 'org,' but because it is a multi-action dispatcher rather than a single verb+resource tool, the purpose is broad.
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 explicitly tells the agent to call action='describe' for the full action/param reference, which is strong usage guidance for a dispatcher. It also flags destructive actions (api-key-delete, oauth-revoke, oauth-revoke-all). However, it does not explicitly contrast when to use this tool versus sibling tools, though the auth scope implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
commentAComments on files: add/list/delete/react, anchor to image regions, A/V timestamps, PDF pages, or text selections. Call action='describe' for the full action/param reference. Destructive: delete, bulk-delete. Verbosity (detail param): list/list-all default to terse (compact rows). details defaults to full (drill-down). Pass an explicit detail='standard'|'full' to override (best-effort — may be a silent no-op until the comments API honors output=; see describe).
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort: 'created' or '-created' (default newest first). | |
| text | No | Max 8192 body / 500 DISPLAY text (mention markup discounted) — the 500 usually BINDS. Both count CHARACTERS — CJK and emoji cost one each, same as ASCII. Mentions count toward 8192 only. A separate 2048-BYTE budget applies to the JSON-encoded `reference` anchor, where each non-ASCII character costs SIX bytes. | |
| emoji | No | Single emoji character. | |
| limit | No | Page size 2-200. | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| detail | No | Per-comment verbosity for list/list-all/details. Defaults: terse for list/list-all (compact rows), full for details (drill-down). See action='describe' for per-level field lists. | |
| offset | No | Offset for pagination. | |
| node_id | No | Storage tree node opaque ID. Both files and folders are nodes — use this name regardless of which. | |
| share_id | No | Alias for profile_id when the profile is a share — implies profile_type=share (so profile_type may be omitted). | |
| reference | No | Anchor: image region, A/V timestamp, PDF page, or text selection. | |
| comment_id | No | Comment opaque ID. | |
| context_id | No | Alias for profile_id (either name works) | |
| profile_id | No | Polymorphic context ID (pair with profile_type=workspace|share). Typed aliases let you omit profile_type: workspace_id (⇒ workspace) / share_id (⇒ share); also context_id. 19-digit profile ID. | |
| properties | No | Arbitrary key-value JSON object metadata (edit action only). Accepts a native object or a JSON string. Merged into the comment's stored properties; server-managed keys (reactions, version, version_hash, edited_at, content_filtered, mentions) supplied here are ignored. | |
| comment_ids | No | Array of comment opaque IDs. | |
| context_type | No | Alias for profile_type (either name works) | |
| profile_type | No | Profile type. | |
| workspace_id | No | Alias for profile_id when the profile is a workspace — implies profile_type=workspace (so profile_type may be omitted). | |
| display_limit | No | list-all only — ignored on the markdown list action. Number of comments to return to the agent (default 10, max 200). Backend page_size unchanged for cache warmth (JSON only). Trims post-fetch only. | |
| include_total | No | Include total count in response. | |
| reference_type | No | Filter by anchor type. | |
| include_deleted | No | Include soft-deleted. | |
| parent_comment_id | No | Parent comment ID for reply (single-level threading). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds meaningful behavioral context: explicitly stating 'Destructive: delete, bulk-delete' and disclosing that the detail override is 'best-effort — may be a silent no-op until the comments API honors output='. This goes beyond the annotations but doesn't fully describe all behaviors, making 4 appropriate.
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 yet information-dense, covering purpose, action discovery, destructive behavior, and verbosity controls in just a few sentences. It is front-loaded with the main purpose and every sentence contributes, with no fluff 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?
Given the tool's complexity (23 parameters, 10 actions, nested reference objects), the description does a good job by summarizing scope, pointing to action='describe' for full details, and covering key behavioral nuances. It doesn't explain return values or the full reference structure, but the schema and describe action compensate, so a 4 is fair.
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 adds a small amount of parameter semantics via the verbosity discussion (detail defaults), but this is already present in the schema's detail parameter description. No significant new parameter meaning is introduced, so the baseline score stands.
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 purpose: 'Comments on files: add/list/delete/react' and explicitly mentions anchoring to image regions, A/V timestamps, PDF pages, or text selections. This specific verb+resource pairing distinguishes it from all sibling tools, none of which relate to comments.
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 clear usage context, such as calling action='describe' for the full reference and explaining verbosity defaults for list/list-all vs details. However, it does not explicitly mention when not to use this tool or compare it to alternatives, so it stops 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.
downloadADownload URLs for files (file-url), folder ZIPs (zip-url), and quickshare links (quickshare-details — DEPRECATED, use the fileshare tool's create action for new shares). Consumes bandwidth credits. Call action='describe' for the full action/param reference.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Operation. Use 'describe' for full action reference. | |
| node_id | No | Storage tree node opaque ID. Both files and folders are nodes — use this name regardless of which. | |
| share_id | No | Alias for profile_id when the profile is a share — implies profile_type=share (so profile_type may be omitted). | |
| context_id | No | Alias for profile_id (either name works) | |
| profile_id | No | Polymorphic context ID. Pair with profile_type=workspace|share. Typed aliases let you omit profile_type: workspace_id (⇒ workspace) / share_id (⇒ share); also context_id / instance_id. 19-digit profile ID or custom name. | |
| version_id | No | Specific file version ID. | |
| instance_id | No | Alias for profile_id (REST/how-to name; profile_id is canonical). | |
| context_type | No | Alias for profile_type (either name works) | |
| profile_type | No | Profile type. | |
| workspace_id | No | Alias for profile_id when the profile is a workspace — implies profile_type=workspace (so profile_type may be omitted). | |
| quickshare_id | No | Quickshare opaque identifier. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and idempotentHint, and the description adds 'Consumes bandwidth credits' which is valuable non-obvious behavior beyond the annotations. It also notes deprecation. No contradiction with structured data.
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, front-loaded with the core purpose, and includes essential caveats (deprecation, bandwidth credits, describe action) without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter, multi-action tool, the description plus 100% schema coverage and the `describe` action provides a fairly complete picture. It doesn't detail return values, but the `describe` action is explicitly offered to fill that 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 coverage is 100%, so baseline is 3. The description adds meaning to the `action` parameter by explaining what each enum value (file-url, zip-url, quickshare-details) does, something the schema's action description omits. It also flags deprecation, enhancing parameter understanding.
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: 'Download URLs for files (file-url), folder ZIPs (zip-url), and quickshare links'. It identifies specific actions and differentiates from siblings like `fileshare` by noting the deprecated quickshare-details and the alternative.
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?
Provides clear usage context by mentioning bandwidth credits and explicitly deprecating quickshare-details with a pointer to the `fileshare` tool for new shares. However, it doesn't explicitly state when to prefer this tool over all alternatives beyond that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
eventAEvent log and activity monitoring for workspaces and shares. Also surfaces the per-member DASHBOARD — a 'what's on your plate' feed of cards (@mentions, file activity) for one workspace, with view-only dismiss/snooze and a best-effort AI overlay. Call action='describe' for the full action/param reference. Verbosity (detail param): search/activity-list/activity-poll default to terse (compact rows). summarize defaults to standard (envelope around the AI summary). details defaults to full (drill-down). Pass an explicit detail='terse'|'standard'|'full' to override (best-effort on summarize/activity-list/activity-poll — only search/details honor output=; see describe).
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Max seconds server holds connection (1-95, default 95). | |
| event | No | Exact event name. See describe action for catalog. | |
| limit | No | Max results (1-250, default 100). | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| cursor | No | Last activity timestamp for incremental polling. | |
| detail | No | Per-record verbosity for search/summarize/details/activity-list/activity-poll. Defaults: terse for search/activity-list/activity-poll (compact rows), standard for summarize, full for details (drill-down). See action='describe' for per-level field lists. | |
| offset | No | Pagination offset. | |
| org_id | No | Filter by organization profile ID. | |
| user_id | No | Filter by user profile ID. | |
| card_key | No | Dashboard card identity "<lane>:<id>" (e.g. "mention:123"). From a dashboard-list card. Required for dashboard-dismiss/dashboard-undismiss; URL-encoded into the path by the server. | |
| category | No | Event category. See describe action for valid values. | |
| event_id | No | Alphanumeric event opaque ID. | |
| share_id | No | Filter by share profile ID. | |
| entity_id | No | Opaque ID of a specific object (file, comment, etc.). Pair with entity_type to disambiguate. 19-digit workspace, share, or File Share ID to monitor (activity-poll long-polls GET /activity/poll/{id}/ — for a File Share id this surfaces its file_share_* feed to WORKSPACE MEMBERS only; recipients get no feed). | |
| object_id | No | Filter by related object opaque ID (file, folder, etc.). | |
| context_id | No | Alias for profile_id (either name works) | |
| profile_id | No | Polymorphic context ID. Pair with profile_type=workspace|share|org|fileshare. Use workspace_id instead when only workspaces are valid. 19-digit profile ID (workspace, share, or File Share). | |
| visibility | No | Filter by event visibility level (external_audit_log | external). Default returns both, excludes internal. | |
| created_max | No | ISO 8601 datetime — events on or before. | |
| created_min | No | ISO 8601 datetime — events on or after. | |
| subcategory | No | Event subcategory. See describe action for valid values. | |
| acknowledged | No | Filter by acknowledgment status. | |
| context_type | No | Alias for profile_type (either name works). | |
| lastactivity | No | Timestamp from prior poll's response. Omit on first call. | |
| profile_type | No | Profile type: "workspace", "share", or "fileshare". `fileshare` is valid for activity-list (long-poll a File Share's feed — workspace members only; recipients get no feed). | |
| snooze_until | No | Optional for dashboard-dismiss: a future "Y-m-d H:i:s UTC" timestamp to snooze the card until (it reappears after). Omit for a permanent dismiss. | |
| user_context | No | Focus guidance for AI summary, e.g. "Focus on uploads". | |
| workspace_id | No | Workspace opaque ID. Use this when only workspaces are valid (not shares or other contexts). For polymorphic contexts use profile_id. Filter by workspace profile ID. | |
| calling_user_id | No | Filter by the user who triggered the event. | |
| parent_event_id | No | Filter by parent event ID for serial/batch events. SCOPE-EXCLUSIVE: cannot combine with any filter other than acknowledged, limit, offset. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations: it explains default verbosity for different actions, describes the dashboard's "view-only dismiss/snooze" nature, and notes that the AI summary is "best-effort" and that only search/details honor the output parameter. This goes well beyond the readOnly/idempotent/destructive hints and does not contradict them.
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 moderately long but well-structured: it opens with the core purpose, then adds dashboard functionality, directs to the describe action, and explains verbosity defaults. Every sentence carries useful information, though the verbosity sentence is dense and could be simplified.
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 tool with 30 parameters, 10 actions, and no output schema, the description provides a solid high-level overview and key behavioral details. It does not enumerate every action or return shape but appropriately delegates to action='describe' for exhaustive reference, making it adequate for initial selection and invocation.
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 largely repeats the detail parameter's default behavior already in the schema and does not add substantial new parameter-level semantics. It points to action='describe' for full references, but that is not additional parameter explanation here.
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 purpose: "Event log and activity monitoring for workspaces and shares" and further specifies the per-member dashboard functionality. It enumerates specific actions (search, summarize, details, acknowledge, activity-list, activity-poll, dashboard-list, dashboard-dismiss, dashboard-undismiss) which distinguishes it from sibling tools focused on other domains.
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 context on when to use this tool (for events/activity monitoring and dashboard interactions) and advises to "Call action='describe' for the full action/param reference." However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
findAUnified search across a workspace or share — ONE query, results GROUPED BY TYPE into buckets (files, metadata [workspace only], comments), each independently paginated and health-reported. Call action='describe' for the full action/param reference. This is the grouped SUPERSET; for a single result type prefer the narrower tools: storage action=search (files only), metadata action=search (lexical metadata fields only). The code-mode search tool searches the API endpoint catalog, not your content.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Alias for search (the name storage + code-mode search use). | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| search | No | Search query string. 1-1024 chars; empty/blank rejected (platform 1605). Searched across every applicable bucket. (Alias: query.) | |
| share_id | No | Alias for profile_id when profile_type=share. | |
| search_in | No | filename | content | both (DEFAULT). filename = name only, find-style. content = the AI's summary + semantic, NOT grep. OMIT unless you mean it — sending it changes the response shape (adds a search_metadata block); omitting reproduces today's behavior byte-for-byte. Pair filename with name_match. | |
| context_id | No | Alias for profile_id. | |
| name_match | No | auto (DEFAULT) | exact | prefix | contains | glob. exact = whole name; prefix = starts with; contains = substring — those three are LITERAL (* and ? are ordinary chars). glob = wildcards over the WHOLE name: *.pdf, report-*.xlsx. Do NOT pre-escape. Applies when search_in is filename or both; auto keeps today's relevance. Precise modes cap the pattern at 256 chars, reject an empty one. | |
| profile_id | No | Workspace or share opaque ID (19-digit numeric ID or custom name). Pair with profile_type. Four accepted aliases besides this one (five id params total): workspace_id, share_id, context_id, instance_id — the supplied id must match profile_type (workspace_id only with profile_type=workspace, share_id only with share). | |
| files_limit | No | files bucket page size (default 25). | |
| instance_id | No | Alias for profile_id (REST/how-to name; profile_id is canonical). | |
| context_type | No | Alias for profile_type. | |
| files_offset | No | files bucket result offset (default 0). | |
| profile_type | No | Profile to search: "workspace" or "share". (Alias: context_type.) | |
| workspace_id | No | Alias for profile_id when profile_type=workspace. | |
| case_sensitive | No | Case-sensitive matching for exact/prefix/contains/glob. Default false (like find -iname), which folds non-ASCII too. Ignored under name_match=auto. | |
| comments_limit | No | comments bucket page size (default 25). | |
| metadata_limit | No | metadata bucket page size (default 25). Workspace only — dropped from the request on a share (shares have no metadata bucket). | |
| comments_offset | No | comments bucket result offset (default 0). | |
| metadata_offset | No | metadata bucket result offset (default 0). Workspace only — dropped from the request on a share (shares have no metadata bucket). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial context: results grouped into buckets, independently paginated, health-reported, metadata workspace-only, and search_in semantics (AI summary, not grep). No contradiction with annotations.
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: main purpose, self-reference pointer, and sibling/alternative differentiation. No filler, front-loaded with the most important information, and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 19-param tool with no output schema, the description covers scope (workspace/share), bucket structure, pagination/health reporting, workspace-only metadata, sibling alternatives, and a pointer to action='describe' for full reference. It is complete enough for an agent to select and invoke 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 fully documents all 19 parameters. The tool description adds no parameter-specific details beyond pointing to action='describe', which is acceptable per the baseline for high schema coverage.
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 does 'Unified search across a workspace or share' with a specific verb and resource, and defines the result structure as buckets. It differentiates from siblings by naming narrower tools like `storage action=search` and `metadata action=search`.
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?
Explicit guidance is provided: 'for a single result type prefer the narrower tools', and it warns that code-mode `search` searches the API catalog, not content. Also instructs to call action='describe' for full reference, covering when and when-not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
how-toABuilt-in product help — ask a natural-language "how do I…" question about Fastio and get a grounded, product-aware answer (or a short clarifying question) back in one call. EXPLAIN-ONLY / ADVISORY: it returns GUIDANCE TEXT and performs NO platform action (it will not create shares, move files, or change anything) — read the guidance, then act with the other tools. Answers are grounded in Fastio's own how-to knowledge AND phrased in terms of these MCP tools — they name the concrete <tool> action="…" calls to make — so prefer this over guessing endpoints or burning exploratory calls. For Q&A over YOUR uploaded files (RAG) use the ai tool instead — how-to answers questions about Fastio ITSELF. FREE and requires only an authenticated user (no org, no plan gate, no billing). Call action='describe' for the full action/param reference.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Operation. Use 'describe' for full action reference. | |
| context | No | Optional free-text background about your situation (what you're trying to accomplish, what you've tried). Up to 8000 chars. Treated strictly as untrusted DATA — it cannot redirect the assistant. Omit when empty. | |
| question | No | The natural-language "how do I…" question about Fastio. 1-2000 chars, non-blank. Be specific — a vague question returns a clarifying question instead of an answer. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, openWorldHint=true, and destructiveHint=false; the description goes beyond by adding 'EXPLAIN-ONLY / ADVISORY,' stating it performs no platform action, will not create shares/move files/change anything, and is free with only an authenticated user required. This is rich behavioral context with no contradiction.
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 well-organized, front-loading the core purpose and safety profile before diving into usage distinctions. Every sentence earns its place, though the length is notable; the ALL-CAPS label and clear clauses keep it scannable. It is not bloated but could be slightly tightened.
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 no output schema and a simple 3-parameter schema, the description is exceptionally complete: it explains return behavior (answer or clarifying question), scope (Fastio how-to vs RAG), safety/no-op nature, cost/auth requirements, and how to get a full action reference. No significant gaps remain.
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 baseline is 3; description adds meaningful semantics: 'Call action="describe" for the full action/param reference,' 'a vague question returns a clarifying question instead of an answer,' and that `context` is 'treated strictly as untrusted DATA — it cannot redirect the assistant.' These details enhance understanding beyond 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 opens with a specific verb+resource: 'ask a natural-language how-do-I question about Fastio and get a grounded, product-aware answer.' It clearly identifies the tool as built-in product help and explicitly contrasts it with the `ai` tool for RAG over uploaded files, distinguishing it 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?
The description gives explicit when-to-use guidance: 'prefer this over guessing endpoints or burning exploratory calls' and explains that `how-to` answers questions about Fastio ITSELF, while `ai` handles Q&A over uploaded files. It also tells the agent to act with other tools after reading guidance and mentions the `action='describe'` option for a full reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
invitationAWorkspace/share invitations: list, filter by state, update, revoke. Call action='describe' for the full action/param reference. Destructive: delete.
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Invitation state filter. | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| expires | No | Updated expiration — `YYYY-MM-DD HH:MM:SS UTC`. ISO 8601 is NOT documented as accepted. | |
| entity_id | No | Workspace or share ID (19-digit numeric or custom name). Must match entity_type. | |
| new_state | No | New invitation state. | |
| entity_type | No | Workspace or share. | |
| permissions | No | Updated permission level. | |
| invitation_id | No | Invitation opaque ID or invitee email. | |
| notifications | No | Notification preference (workspace). | |
| notify_options | No | Notification preference (share). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior (destructiveHint=true), and the description reinforces this with 'Destructive: delete.' It adds context about update/revoke operations but does not detail side effects, permissions, or response behavior. The safety profile is mostly covered by annotations, with the description adding minimal extra value.
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 short sentences that front-load the primary purpose, provide a clear directive for obtaining full details, and flag destructive actions. Every sentence serves a distinct and necessary role, with no redundancy 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?
Given the tool's complexity (10 parameters, multiple actions) and absence of an output schema, the description provides a high-level overview and directs to action='describe' for complete details. It does not explicitly list all actions or parameter groups, but the describe reference compensates, making the description sufficiently complete for initial orientation.
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 all 10 parameters are already described in the schema. The description adds no additional parameter semantics beyond referencing action='describe' for full details. This matches the baseline for high schema coverage; no extra credit needed.
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 it manages 'Workspace/share invitations' with actions like list, filter, update, revoke, which distinguishes it from sibling tools like share or member. It could be more exhaustive by listing all actions (e.g., delete, describe), but the pointer to action='describe' compensates, making the purpose evident.
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 implies usage when managing workspace/share invitations, but it does not explicitly state when to use this tool versus alternatives or mention exclusions. The advice to call action='describe' for the full reference is helpful though limited. No direct comparison to sibling tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
memberAWorkspace/share member management: list, add, remove, update, transfer ownership, join, leave. Call action='describe' for the full action/param reference. Destructive: remove.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | Share permission level. | |
| limit | No | Maximum number of items to return (1-500, default 100) | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| offset | No | Number of items to skip (default 0) | |
| expires | No | Membership expiration — `YYYY-MM-DD HH:MM:SS UTC` for BOTH workspace and share. ISO 8601 is NOT accepted (406). | |
| message | No | Invitation email message (10-255 chars). | |
| user_id | No | User profile ID (share). | |
| entity_id | No | Workspace or share ID (19-digit numeric or custom name). Must match entity_type. | |
| member_id | No | Member ID (workspace). | |
| expiration | No | Alias for expires (share only). | |
| entity_type | No | Workspace or share. | |
| permissions | No | Workspace permission level. | |
| display_limit | No | How many members to return for the list action. Default 10, max 500. The MCP trims post-fetch; backend paging stays MCP-internal so the platform cache stays warm. | |
| notifications | No | Notification preference (workspace string). | |
| invitation_key | No | Invitation key string. | |
| notify_options | No | Notification preference (share). | |
| email_or_user_id | No | Email (to invite) or user ID (to add directly). | |
| invitation_action | No | Accept or decline. | |
| force_notification | No | Force notify existing user (workspace-only). | |
| invitation_expires | No | Invitation expiration ISO 8601 (workspace-only). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true. The description goes beyond this by identifying 'remove' as the destructive action and by disclosing the self-describing action='describe' behavior. This adds specific context without contradicting annotations.
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 short sentences: purpose with operations, the 'describe' instruction, and a destructive warning. Every sentence earns its place with no redundancy 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?
Given the tool's complexity (10 actions, 20 parameters, no output schema), the description provides a concise overview and leverages the built-in 'describe' action for full detail. It doesn't outline return values, but that's acceptable without an output schema. It is sufficient for orientation.
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%, meaning all 20 parameters have descriptions. The description text itself adds no parameter-level detail beyond pointing to action='describe' for more information, so it meets the baseline for fully-covered schemas.
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 specifies 'Workspace/share member management' and enumerates the operations: list, add, remove, update, transfer ownership, join, leave. This distinguishes it from sibling tools like share (managing shares) and workspace (workspace settings).
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 (member management for workspace/share) and instructs to call action='describe' for the full action/param reference. It does not explicitly contrast with sibling tools or state exclusions, but the resource scope is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
metadataAAI metadata templates & extraction (the unstructured-data automation pipeline): template CRUD/clone, assign/resolve, the AI pipeline (eligible -> preview-match -> suggest-fields -> template-create -> nodes-add/-list -> auto-match -> extract-all), saved views, and lexical metadata search. Call action='describe' for the full action/param reference. Node-level metadata (get/set/delete/extract on a single file) lives on the storage tool. Destructive: template-delete, view-delete, nodes-remove. AI/credit side-effects: preview-match, suggest-fields, auto-match, extract-all (each spends AI credits).
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | search keyword(s). 1-1024 chars. Multi-token = ALL tokens (AND); case-insensitive; substring for <=64 chars, else whole-word. | |
| name | No | Template name (1-255 chars: template-create/-update/-clone and preview-match), OR an optional saved-view label on view-save (≤30 chars; omit to keep the existing label). | |
| force | No | extract-all: when 'true', re-extract every mapped node even if it already has KV data (re-extract flow). Default 'false' skips nodes with values present. | |
| limit | No | search: page size (1-100, default 100). | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| config | No | view-save config JSON: `{version:1, columns:[{field,visible?,width?}], sort:{field,dir}, filters:[{field,operator,value_type,value}]}`. Max 5 filters AND-chained; operator in `= != < <= > >=`; value_type in `string|int|float|bool`. | |
| cursor | No | eligible/nodes-list: opaque pagination cursor from a prior page's response. Omit for the first page. | |
| fields | No | JSON array of field defs (template-create/-update/-clone). At least one field must have autoextract:true (default) or API returns 1605. Each: {name, description, type (string|int|float|bool|json|url|datetime), min?, max?, default?, fixed_list?, can_be_null?, autoextract?}. | |
| offset | No | search: results to skip (default 0). offset+limit must stay <= 10000. | |
| filters | No | template-list filter (default 'all'): all|enabled|disabled|custom|system. (Replaces the old workspace `template_filter` param.) | |
| node_id | No | Storage tree node opaque ID (used by template-resolve, and template-assign to scope an assignment). | |
| category | No | Metadata template category (accepted but ignored server-side — no effect). | |
| node_ids | No | JSON array of node IDs. suggest-fields: 1-25 file nodes. nodes-add/-remove: nodes to map/unmap (files+notes; folders/links rejected) — deduped first-seen, max 50 unique per call (the server hard-rejects >50 per request; the per-template TOTAL node cap is separate and enforced server-side). | |
| sort_dir | No | nodes-list: asc|desc (only with sort_field). | |
| page_size | No | eligible/nodes-list: cursor page size (1-250, default 100). Server caps at 250. | |
| batch_size | No | auto-match: optional batch-size override (clamped server-side). Omit for default. | |
| sort_field | No | nodes-list: optional template field name to sort by. | |
| description | No | Template description. ≤255 chars, empty allowed (template-create/-update/-clone). preview-match: required, 1-2000. suggest-fields: optional, ≤2000. | |
| template_id | No | Metadata template ID (e.g. mt_abc123). For search, restricts to nodes with values from this template (custom fields excluded). | |
| user_context | No | suggest-fields: short view/template hint (1-64 chars, letters/numbers/spaces). Example: "photo collection". | |
| workspace_id | No | Workspace opaque ID (19-digit numeric ID or custom name). Required for every action. | |
| display_limit | No | search: how many items to return post-fetch. Default 10, max 100 (the backend fetches at most 100 per page — a higher value has no effect; use offset to page past 100). | |
| extract_fields | No | extract-all: JSON array of field names to restrict the batch job to (e.g. `["vendor","amount"]`); omit for all fields. | |
| parent_node_id | No | view-export destination folder opaque ID (must be a folder, not trashed). Omit for workspace root. | |
| describe_action | No | When action='describe', narrow the output to ONE action's full params/notes (e.g. 'template-list'). Omit to get the compact action index. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include generic destructiveHint=true, but the description names specific destructive actions (template-delete, view-delete, nodes-remove) and AI/credit side-effects (preview-match, suggest-fields, auto-match, extract-all). This provides concrete behavioral context beyond the annotations.
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 appropriate for the tool's complexity. It front-loads the main purpose, then quickly adds boundary, destructive, and cost notes. Each sentence contributes, though it is longer than minimal.
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 25-param tool with no output schema, the description covers the domain, action families, pipeline order, destructive/cost warnings, and the storage boundary. It delegates detailed reference to `describe`, which is reasonable but leaves return/error behavior unaddressed.
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% for 25 params, so baseline is 3. The description does not add param-level semantics; it only gives a high-level categorization of actions. The pointer to `describe` is a reference but not inherent parameter meaning.
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 purpose: 'AI metadata templates & extraction (the unstructured-data automation pipeline)' and enumerates the key action families (template CRUD/clone, assign/resolve, AI pipeline, saved views, search). It distinguishes from siblings by explicitly noting node-level metadata lives on the `storage` tool.
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 alternative: 'Node-level metadata (get/set/delete/extract on a single file) lives on the `storage` tool.' It also advises calling `action='describe'` for the full action/param reference, guiding the agent on how to get more detail when needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
orgAOrganization management: CRUD, billing, members, invitations, ownership transfer, assets, discovery. Call action='describe' for the full action/param reference. Destructive: close (permanently deletes org and all data).
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Display name (3-100 chars). | |
| role | No | Org permission level — `member` or `admin` ONLY. `owner` is not assignable (it is returned when READING members, alongside admin/member). `guest` and `view` are WORKSPACE/SHARE roles and are rejected here (1605). | |
| No | Email address of user to invite. | ||
| limit | No | Page size. | |
| meter | No | Meter type, e.g. storage_bytes, transfer_bytes, ai_tokens. | |
| state | No | Invitation state, e.g. pending, accepted. | |
| token | No | Transfer token for ownership claim. | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| detail | No | Per-entity verbosity for list/discover-*/members/list-workspaces/details. Defaults: terse for list/discover-*/members/list-workspaces, full for details. See action='describe' for per-level field lists. | |
| domain | No | URL-safe subdomain (2-80 chars, lowercase alphanumeric + hyphens, globally unique, not reserved). | |
| offset | No | Pagination offset (0-based). | |
| org_id | No | Organization 19-digit ID or domain string. | |
| confirm | No | Confirmation string, must match org domain or ID. | |
| content | No | Plain text content. asset-upload: e.g. SVG body. | |
| expires | No | Updated expiration datetime. | |
| message | No | Custom invitation email message (10-255 chars). | |
| user_id | No | User ID. | |
| end_time | No | End datetime (default now). | |
| industry | No | Industry type, e.g. technology, healthcare, financial. | |
| metadata | No | Additional metadata as JSON array string. | |
| share_id | No | Filter by share ID. | |
| token_id | No | Transfer token ID. | |
| file_name | No | Original file name, e.g. logo.png. | |
| member_id | No | User ID or email of member. | |
| perm_join | No | Permission level required to join workspace. | |
| asset_name | No | Asset name, e.g. "logo", "banner". | |
| start_time | No | Start datetime (default 30 days ago). | |
| description | No | Description (10-1000 chars). | |
| domain_name | No | Domain to check for availability. | |
| file_base64 | No | Base64 file content for binary assets. | |
| folder_name | No | URL-safe workspace folder name (4-80 chars). | |
| join_action | No | Invitation action: accept or decline (default accept). Appended to the join URL path — restricted to these two values to prevent path injection. | |
| permissions | No | Updated permission level. | |
| twitter_url | No | Twitter/X profile URL. | |
| youtube_url | No | YouTube channel URL. | |
| accent_color | No | Brand accent color as JSON. | |
| billing_plan | No | Paid plan ID for billing-create, e.g. 'solo_monthly', 'business_v2_monthly', 'growth_monthly' (each has an annual variant). New orgs require a paid plan — free/agent plans are legacy and closed to new subscriptions; legacy 'pro_monthly'/'business_monthly' are also closed. Call billing-plans for the currently-offered plan IDs. | |
| content_type | No | MIME type, e.g. image/png. Defaults to application/octet-stream. | |
| facebook_url | No | Facebook page URL. | |
| homepage_url | No | Organization website URL. | |
| intelligence | No | Enable RAG indexing. COSTS 10 credits/page. Defaults "false". See describe. | |
| workspace_id | No | Workspace opaque ID. Use this when only workspaces are valid (not shares or other contexts). For polymorphic contexts use profile_id. Filter by workspace ID. | |
| billing_email | No | Billing contact email. | |
| display_limit | No | Number of orgs to return to the agent (default 10, max 100). Backend page_size unchanged for cache warmth — applies to list. Trims post-fetch only. | |
| instagram_url | No | Instagram profile URL. | |
| invitation_id | No | Invitation ID or invitee email. | |
| owner_defined | No | Custom owner-defined properties as JSON. | |
| invitation_key | No | Invitation key from invite link. | |
| starting_after | No | billing-invoices cursor: pass a prior invoice's `id` to fetch the next page (cursor pagination, not offset). | |
| use_background | No | Enable/disable background, "true"/"false". | |
| background_mode | No | Background display mode, e.g. 'stretched', 'fixed'. | |
| describe_action | No | When action='describe', narrow the output to ONE action's full params/notes (e.g. 'list'). Omit to get the compact action index. | |
| background_color | No | Background color as JSON. | |
| background_color1 | No | Primary background color as JSON. | |
| background_color2 | No | Secondary background color as JSON. | |
| perm_member_manage | No | Who can manage members, e.g. 'Owner only'. | |
| perm_authorized_domains | No | Authorized email domain for auto-join. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true, and the description adds a specific, high-impact behavioral warning: 'close (permanently deletes org and all data).' This is valuable context beyond the generic annotation. However, it does not elaborate on other potentially destructive actions like asset-delete or transfer-ownership, so it's not fully comprehensive.
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 two sentences, front-loaded with purpose and scope, ending with a critical destructive warning and a self-help pointer. Every sentence earns its place with zero fluff. It is appropriately sized for a high-level overview that delegates detail to the describe action.
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 57 parameters, 40+ actions, and no output schema, this description is skeletal. It gives a high-level capability list and points to describe for the full reference, which is a useful workaround, but it does not cover return values, authentication, or action-specific side effects. The description relies heavily on the agent calling describe before use, which is acceptable 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%, with each of the 57 parameters already having detailed descriptions. The tool description text itself adds no parameter-level semantics, so the baseline of 3 applies. It correctly points to action='describe' for deeper parameter details, but that is meta-guidance, not 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?
The description clearly states the tool manages organizations, listing major capabilities (CRUD, billing, members, invitations, ownership transfer, assets, discovery). This is specific and avoids tautology, but it does not differentiate org from sibling tools like member, invitation, or workspace, which appear to be sub-features.
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 implies usage by listing the tool's broad scope, but gives no explicit guidance on when to use org versus sibling tools. The only hint is 'Call action='describe' for the full action/param reference,' which is a navigation aid rather than a decision rule. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
roomACoordination Rooms — a private, workspace-scoped space for agentic teams (agents + humans) to join, post messages, track each other's status/presence, and hand off files. Create is idempotent per (workspace, topic_slug). Presence is refreshed by ANY room call; liveness ≠ progress. Hand files off via the upload tool into the room's storage. Call action='describe' for the full protocol + action/param reference.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | 1-8192 CHARACTERS, counted in code points — a CJK or emoji character costs exactly one, same as ASCII. (A byte ceiling underneath this used to refuse non-ASCII far sooner; it was raised out of reach on 2026-08-05.) post only. Do NOT put secrets here. File refs: `@[file:<id>:<name>]` is valid here and counts toward the 8192 in FULL (no discount on this path); full grammar in action=describe. | |
| goal | No | create only, OPTIONAL. 1-500 chars, no control chars — blank is REJECTED, so omit it rather than sending an empty string. On adopt (created:false) a goal that DIFFERS from the stored one is refused 409 (120719), not discarded: omit it to join, or fix it with share action=update room_goal. Correctable after creation. No secrets. | |
| kind | No | post only. One of: say|ask|answer|status|join|done. | |
| sort | No | messages only. asc (DEFAULT) = oldest-first, FOLLOWS the log and is never finished — has_more:false just means caught up for now, so keep polling. desc = newest-first BACKFILL and IS terminal: a page that does not fill means you reached the beginning. Joining a busy room? Do NOT drain from the start — read the tail once with sort=desc, then follow with since=<latest_cursor>. | |
| limit | No | messages only. Page size (default 50, max 200). | |
| since | No | messages only. Opaque keyset cursor from a prior page's next_cursor (or latest_cursor to start the follow loop). Omit for the first page; never parse it. A cursor REMEMBERS its direction — send it back WITHOUT sort; passing a conflicting sort is an error, not a silent flip. To change direction, drop since and start a new page. | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| key_id | No | agents-revoke only. The key_id of a room-minted agent key (from agents-list). | |
| status | No | status only. Self-reported; transitions are NOT enforced. One of: investigating|joining|working|testing|waiting|needs_peer|resolved_pending|done|blocked. | |
| room_id | No | Room ID (a 19-digit share profile ID; from create). | |
| topic_slug | No | create only. 1-64 chars, lowercase alnum + internal hyphens (no leading/trailing hyphen). Create is idempotent per (workspace, topic_slug). | |
| agent_label | No | Your agent's PUBLIC SENDER IDENTITY — the name peers and humans see on every message and roster row. Use a MEANINGFUL, STABLE name (your real assistant name), never a placeholder. Max 120 chars, room-wide unique among LIVE participants (409 if held). Pass it on state/status/post/messages/wait or your presence drifts to alive:false. Full rules: action=describe. | |
| ttl_seconds | No | invite-create only. One-time link lifetime in seconds (default 1800 = 30 min, capped at 3600 = 1 h). | |
| display_text | No | post only. Optional short display summary (max 500 chars). | |
| intelligence | No | create only. Enable AI on the room (requires an intelligence-capable plan). Default false. | |
| lastactivity | No | wait only. Activity cursor from a prior wait response — echo it VERBATIM (it carries fractional seconds; truncating/reformatting to Y-m-d H:i:s causes instant stale re-wakes). Omit on the first wait. | |
| wait_seconds | No | wait only. Max seconds the server holds the poll open (1-20, default 20). | |
| workspace_id | No | 19-digit workspace profile ID (create — you must be a MEMBER). | |
| participant_id | No | participant-remove only. The roster participant `id` (stable identity, from `state`) to remove — NOT the agent_label. | |
| status_summary | No | status only. Free-text summary of what you're doing (max 8,192 CHARACTERS, code points — not the 500 that caps a message's display_text). | |
| status_version | No | status only. The CAS version you last read. REQUIRED for an existing participant — omit ONLY on your VERY FIRST join. A re-keyed agent already HAS a row, so read its status_version from `state` first rather than omitting. On CAS conflict (192604 / 182596) retry with error.params.current_status_version. See action=describe. | |
| suggested_label | No | invite-create only. Default agent_label for the redeeming agent — its PUBLIC SENDER IDENTITY in the room. Suggest a MEANINGFUL, STABLE name, never a placeholder. 1-120 chars, no control chars, room-wide unique among LIVE participants (409 if held). Baked into the link; the redeemer may override. See action=describe. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds several non-obvious behavioral traits beyond annotations: idempotent creation per (workspace, topic_slug), presence refresh on ANY room call, and the liveness ≠ progress caveat. These are valuable context that annotations (readOnlyHint=false, destructiveHint=true) do not capture. It does not enumerate destructive actions, but the schema's action names (participant-remove, agents-revoke, leave) are self-descriptive, and the annotations already set the destructive expectation. This is well above the minimal bar.
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 exactly two sentences, front-loaded with purpose, then efficiently covers key semantics (idempotency, presence, file handoff, describe pointer) without filler. Every clause adds value and the structure is easy to scan.
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 22 parameters and multiple actions, the description gives a solid orientation layer and explicitly directs the agent to action='describe' for the full protocol, which compensates for the lack of an output schema. It doesn't list every action, but the schema already enumerates them, and the presence/idempotency details are enough to prevent misuse at a high level. Slightly more could be said about the multi-action dispatcher nature, but the present guidance is sufficient.
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% with rich, parameter-level descriptions, so the baseline is 3. The main description adds little parameter semantics beyond what the schema already provides; for instance, the idempotency note appears in both the description and the topic_slug parameter description. The description's pointer to action='describe' is useful, but the schema already carries the heavy lifting for parameter understanding.
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 defines the tool as a workspace-scoped coordination space for agentic teams, listing core verbs (join, post messages, track status/presence, hand off files) and distinguishing it from siblings by framing it as the shared-team-space resource. It also mentions idempotent creation, which adds scope specificity. This is far beyond a vague or tautological purpose 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 provides an explicit alternative for file handoff ('Hand files off via the `upload` tool'), showing when not to use room for that purpose. It also directs users to call action='describe' for the full protocol and action/param reference, which is a useful usage path. However, it does not contrast room with other sibling tools (e.g., auth, member) beyond the upload example, so the guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
storageAFiles & folders on workspaces/shares: list, search, copy, move, delete, rename, trash, transfer, versions, locks, previews, and per-node metadata (get/set/delete/extract/versions). Call action='describe' for the full action/param reference. Destructive: purge (irreversible). delete moves to trash. metadata-delete removes metadata keys. Verbosity (detail param): list/recent/search/trash-list default to terse (compact rows). details defaults to full (drill-down). Pass an explicit detail='standard'|'full' to override.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Alias for query. | |
| keys | No | metadata-delete: JSON array of metadata keys to delete (omit to clear all). | |
| name | No | Name for new folder or file. | |
| size | No | Size preset: "IconSmall", "IconMedium", "Preview", or custom. | |
| type | No | Filter by node type. | |
| limit | No | Max results (1-500, default 100). | |
| query | No | Search query — keyword, or keyword + semantic when intelligence is on. | |
| width | No | Target width in pixels. | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| cursor | No | Opaque cursor from a previous response. | |
| detail | No | Per-node verbosity for list/recent/search/trash-list/details. Defaults: terse for list/recent/search/trash-list, full for details. Bump to full when you need ai.attach (files_attach preflight), virus, hashes, file_attributes, lock_info, or long-form summaries. See action='describe' for per-level field lists. Not to be confused with `details` (search-only). | |
| height | No | Target height in pixels. | |
| offset | No | Results to skip (default 0). | |
| details | No | Search-only. Return fully-hydrated node objects per result (default limit drops to 10). Distinct from `detail` — call action='describe' for the contrast. | |
| node_id | No | Storage tree node opaque ID. Both files and folders are nodes — use this name regardless of which. Storage node opaque ID, or 'root'. On `list`, the target folder may also be given as parent_node_id or parent_id (aliases), and defaults to 'root' (the storage top level) when all three are omitted. | |
| sort_by | No | Sort column (default: name). | |
| max_size | No | Max read-content bytes (default 512000, max 1048576). | |
| new_name | No | New name for file or folder. | |
| node_ids | No | Storage node opaque IDs (details: 1-25 max). | |
| order_by | No | metadata-list-files: field key to sort by. | |
| share_id | No | For add-link: the target share to link (workspace-only). For the dual-type actions (list/details/copy/move/etc.): a profile alias implying profile_type=share — the share you are operating in (so profile_type may be omitted). | |
| sort_dir | No | Sort direction (default: asc). | |
| node_type | No | rename-only OPTIONAL hint: the node's type, when the caller already knows it. Notes route to a dedicated endpoint, so supplying node_type lets rename skip the /details/ type-probe round-trip. Omit to have rename probe automatically. Distinct from the list/recent `type` filter. | |
| parent_id | No | Alias for node_id on `list` (the folder whose contents to list), or 'root'. `list` defaults to 'root' when omitted. | |
| search_in | No | filename | content | both (DEFAULT). filename = name only, find-style. content = the AI's summary + semantic, NOT grep. OMIT unless you mean it — sending it changes the response shape (adds a search_metadata block); omitting reproduces today's behavior byte-for-byte. Pair filename with name_match. | |
| upload_id | No | Opaque ID of completed upload session. | |
| context_id | No | Alias for profile_id (either name works) | |
| key_values | No | metadata-set: JSON object of key-value pairs matching template fields. | |
| lock_token | No | lock-release/lock-heartbeat only — the token returned by lock-acquire. REQUIRED to release or refresh a lock. | |
| name_match | No | auto (DEFAULT) | exact | prefix | contains | glob. exact = whole name; prefix = starts with; contains = substring — those three are LITERAL (* and ? are ordinary chars). glob = wildcards over the WHOLE name: *.pdf, report-*.xlsx. Do NOT pre-escape. Applies when search_in is filename or both; auto keeps today's relevance. Precise modes cap the pattern at 256 chars, reject an empty one. | |
| order_desc | No | metadata-list-files: sort descending ('true' or 'false'). | |
| profile_id | No | Polymorphic context ID (pair with profile_type=workspace|share). Typed aliases let you omit profile_type: workspace_id (⇒ workspace) / share_id (⇒ share, on dual-type actions); also context_id / instance_id. 19-digit workspace or share ID, or custom name. | |
| version_id | No | Version ID to restore. | |
| as_markdown | No | Opt-in (list/recent/search/details/trash-list): when true, the platform renders the response as GitHub-flavored Markdown (?output=<detail>,markdown) for compact, human/agent-readable output instead of JSON. Omit (default) for the unchanged JSON shape with web_url enrichment + _next hints. Markdown is a passthrough — no client-side reshaping. | |
| files_scope | No | Scope semantic search to file versions. See describe for full constraints. | |
| instance_id | No | Alias for profile_id (REST/how-to name; profile_id is canonical). | |
| template_id | No | Metadata template ID (e.g. mt_abc123). Required for metadata-set/metadata-list-files. The template SYSTEM (CRUD/assign/AI-extraction) lives on the `metadata` tool. | |
| context_type | No | Alias for profile_type (either name works) | |
| preview_type | No | Type of preview to generate. See describe for which preview_types apply to which file categories. | |
| profile_type | No | Profile type: "workspace" or "share". | |
| workspace_id | No | Alias for profile_id when the profile is a workspace — implies profile_type=workspace (so profile_type may be omitted). Valid on every storage action. | |
| display_limit | No | How many items to return. Default 10, max 500. The MCP trims post-fetch; backend cache stays warm. Used by: list, recent, search. list/recent paginate via the `cursor` param; search paginates via `offset` (increase offset by the page size) for additional pages. | |
| folders_scope | No | Scope semantic search to folders via BFS. See describe for full constraints. | |
| output_format | No | Output format: "png", "jpg", "webp". | |
| transfer_mode | No | 'copy' (default) or 'move'. 'move' invalid for node_id 'root'. | |
| case_sensitive | No | Case-sensitive matching for exact/prefix/contains/glob. Default false (like find -iname), which folds non-ASCII too. Ignored under name_match=auto. | |
| dest_parent_id | No | Destination parent folder opaque ID, or 'root'. Primary param for transfer (the parent in the OTHER instance). For copy/move within the same instance use target_parent_id — dest_parent_id is also accepted there as an alias. | |
| extract_fields | No | metadata-extract: JSON array of field names to extract (e.g. `["vendor","amount"]`); omit/null for full row. | |
| parent_node_id | No | Parent folder opaque ID, or 'root'. (On `list`, also accepted as an alias for node_id — the folder to list; `list` defaults to 'root' when omitted.) | |
| transform_name | No | Transform name, e.g. "image" for resize/crop/format. | |
| describe_action | No | When action='describe', narrow the output to ONE action's full params/notes (e.g. 'list'). Omit to get the compact action index. | |
| dest_instance_id | No | Destination workspace or share profile ID. | |
| metadata_filters | No | metadata-list-files: JSON filter criteria for the metadata file listing. | |
| target_parent_id | No | Destination folder opaque ID, or 'root'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description clearly discloses that purge is irreversible, delete moves to trash, metadata-delete removes keys, and detail verbosity defaults per action. This adds valuable behavioral context without contradicting the annotations.
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 dense paragraph but front-loaded with a capability list, then safety notes, then verbosity guidance. It is appropriately sized for a tool with 30+ actions, though it could be slightly tighter.
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 tool (54 params, no output schema), the description covers critical safety behaviors and directs to action='describe' for the full reference. It is complete enough for initial invocation, though deeper behavior is delegated to the describe action.
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 repeats some parameter details already in the schema (e.g., detail defaults) but does not add significant new semantics for the 54 parameters. It's acceptable but does not elevate beyond 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 'Files & folders on workspaces/shares' followed by an explicit list of operations (list, search, copy, move, delete, rename, trash, transfer, versions, locks, previews, metadata), making the tool's scope clear. It distinguishes from sibling tools like upload/download by focusing on management operations, though it's a multi-action tool rather than a single verb+resource.
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 context on destructive actions (purge irreversible, delete moves to trash) and points to action='describe' for the full reference, but it does not explicitly state when to use this tool versus siblings or list exclusions. Usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
uploadAFile upload: stream-upload (one-shot — auto-finalizes, no filesize needed), chunked (create-session → chunk → finalize, for exact-known-size or files split across blobs), web URL import, and batch (many small files). Call action='describe' for the full action/param reference. Side effects: finalize/stream/stream-upload/web-import/batch create files and consume storage credits. Same-name uploads to a folder OVERWRITE the existing node in place (preserved as a recoverable version). BYTES → SERVER: the DEFAULT for every file/binary is the POST /blob sidecar — a plain HTTP POST outside the MCP pipe (the create-session/blob-info response hands you a ready-to-run curl command) that returns a blob_id you pass to stream-upload/chunk/batch: no base64, no MCP size limit, up to 100 MB. Use content_base64 (inline base64, capped a few MB by the MCP transport) ONLY when your client cannot make the POST /blob call. content is small text only (verbatim UTF-8). UPLOAD STRATEGY (read top-to-bottom, pick the FIRST that matches): (1) Have a URL? → web-import (single call). (2) DEFAULT for a file/binary → POST /blob, then stream-upload with blob_id (single call, auto-finalizes, NO filesize required). Unknown/generated size and no way to reach /blob → stream-upload with content_base64. (3) Known exact byte count, or a large file split across blobs → create-session + chunk(blob_id) + finalize. filesize must match the bytes you actually upload — mismatch causes finalize to fail with code 10522 and you must cancel the session. (4) Multiple small files (≤4 MB each, ≤200 total) into one folder? → batch. Prefer blob_id (POST /blob) for every file/binary upload; fall back to content_base64 only when you cannot reach /blob. Do NOT guess filesize for generated content — use stream-upload. max_size is a hard ceiling that aborts mid-transfer — always overestimate or omit (server uses plan limit).
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Org ID for limit resolution. | |
| url | No | Source URL to import from. | |
| hash | No | File hash for verification. | |
| plan | No | Override billing plan to check (e.g. free, pro). | |
| wait | No | Long-poll wait in SECONDS, 1-590 (NOT milliseconds; 0/omitted returns immediately). The server holds the connection until the upload reaches a terminal status. Sending a millisecond value here would hold for minutes and blow past the tool-call timeout. | |
| files | No | Batch manifest (1..200 entries). Each: filename + one of blob_id/content/content_base64. | |
| limit | No | Max results (1-100, default 50). | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| offset | No | Pagination offset. | |
| status | No | Filter by status. | |
| stream | No | Stream mode — size optional, single POST, auto-finalizes. | |
| blob_id | No | Blob ID from POST /blob — the **default source** for all file & binary uploads (no base64, no MCP size limit, up to 100 MB). Single-use. | |
| content | No | **Text only** — stored verbatim UTF-8. Do NOT pass base64 here (use content_base64). One of content/content_base64/blob_id. | |
| creator | No | Client identifier echoed back (alphanumeric + hyphens). | |
| file_id | No | File ID for update context. | |
| blob_ref | No | Alias for blob_id (deprecated). Accepted on chunk/stream/stream-upload only. | |
| chunk_id | No | Specific chunk number (omit for all). | |
| filename | No | File name. Optional when target_node_id is set (auto-resolved); pass to rename-on-replace. | |
| filesize | No | Total file size in bytes. | |
| max_size | No | Stream-body byte ceiling — aborts mid-transfer if exceeded. Always overestimate; omit to use plan limit. Stream sessions only. | |
| password | No | File Share link password (profile_type=fileshare only). Forwarded ONLY as the x-ve-password header on every upload phase — never in a URL/log. Supply when the target share is password-protected. | |
| share_id | No | Alias for profile_id when the profile is a share — implies profile_type=share (so profile_type may be omitted). | |
| folder_id | No | Target folder OpaqueId or "root". Omit for instance root. | |
| hash_algo | No | Hash algorithm (e.g. 'sha256'). | |
| upload_id | No | Upload session ID or web upload job ID. | |
| chunk_size | No | Chunk size in bytes (server picks default). | |
| context_id | No | Alias for profile_id (either name works) | |
| profile_id | No | Polymorphic context ID (pair with profile_type=workspace|share|fileshare). Typed aliases let you omit profile_type: workspace_id (⇒ workspace) / share_id (⇒ share); also context_id / instance_id. Target workspace/share ID, or the File Share id for a fileshare write-back. fileshare has NO typed alias — pass profile_type=fileshare explicitly. | |
| instance_id | No | Target workspace/share ID — also the profile_id alias for upload flows; profile_id is canonical. | |
| chunk_number | No | 1-indexed chunk number. | |
| context_type | No | Alias for profile_type (either name works). | |
| include_hash | No | Compute SHA-256 client-side for entries without a hash (default true when omitted). | |
| profile_type | No | Target type: workspace | share | fileshare (alias: context_type). Use `fileshare` ONLY for content write-back to a File Share's bound file (requires target_node_id = the bound node id from `fileshare details`; create-style new-file flows are rejected for fileshare). | |
| workspace_id | No | Alias for profile_id when the profile is a workspace — implies profile_type=workspace (so profile_type may be omitted). | |
| if_version_id | No | File Share write-back compare-and-swap (profile_type=fileshare only). Pass the version id your edit was based on (from fileshare details / versions-list). If the file advanced, NOTHING is written — the session ends assembly_failed with CONFLICT_VERSION_MISMATCH:<id>; rebase and retry. Omitting it is last-write-wins. See action=describe. | |
| action_context | No | Context: create or update. | |
| content_base64 | No | Base64-encoded **binary**, server-decoded (whitespace stripped). **Fallback only** — capped a few MB by the MCP transport. Prefer `blob_id` (POST /blob) for any file/binary; use this only when your client cannot make the POST /blob call. | |
| parent_node_id | No | Parent folder OpaqueId or "root". On create-session, stream-upload, and web-import, folder_id is accepted as an alias (either name works). | |
| target_node_id | No | Overwrite this specific node (preserves node_id; new version). When set, parent_node_id is ignored and filename is optional (auto-resolved). Must be a file node. REQUIRED for profile_type=fileshare write-back — set it to the File Share's bound node id (from `fileshare details` → fileshare.file.id). | |
| describe_action | No | When action='describe', narrow the output to ONE action's full params/notes (e.g. 'chunk'). Omit to get the compact action index. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, and the description adds concrete side effects: 'finalize/stream/stream-upload/web-import/batch create files and consume storage credits' and 'Same-name uploads... OVERWRITE the existing node in place (preserved as a recoverable version).' It also discloses the POST /blob sidecar default, 100 MB limit, and error code 10522 for filesize mismatch, going well beyond the safety hint.
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 long but well-structured with clear sections and a numbered strategy. It exhibits minor redundancy (e.g., 'Prefer blob_id... fall back to content_base64' appears twice), but each section earns its place given the tool's complexity. The front-loaded decision tree helps the agent act immediately.
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 tool's 40 parameters and multiple actions, the description covers upload modes, default transfer path, overwrite semantics, side effects, and failure modes, and points to action='describe' for full reference. No output schema exists, so return-value detail is unnecessary; the description is thorough enough to select and invoke the correct action.
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?
Despite 100% schema description coverage, the description adds crucial inter-parameter semantics: explains the relationship between blob_id/content/content_base64, the fallback ordering, that `content` is text-only, filesize must match actual bytes, and max_size should be overestimated. It also clarifies action='describe' and the sidecar curl flow, giving meaning the schema alone lacks.
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 'File upload: stream-upload (one-shot...), chunked..., web URL import, and batch (many small files)', which clearly defines the tool's scope as a multi-strategy upload tool. It names specific actions and resources, and the title 'File Upload' reinforces the purpose. Although it doesn't explicitly contrast sibling tools like download, the verb+resource is unambiguous.
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 'UPLOAD STRATEGY' section provides an explicit top-to-bottom decision procedure: use web-import for URLs, POST /blob + stream-upload as the default, create-session + chunk + finalize for known sizes, and batch for many small files. It also explicitly says 'Do NOT guess filesize' and directs to action='describe' for full reference, giving both when-to-use and when-not-to guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
userAUser profile, contacts, invitations, and assets. Call action='describe' for the full action/param reference. Destructive: close.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of items to return (1-500, default 100) | |
| query | No | Contact search substring. | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| offset | No | Number of items to skip (default 0) | |
| content | No | Plain text content for asset upload. | |
| user_id | No | 19-digit user ID or email. | |
| archived | No | True for archived shares, false for active. | |
| filename | No | Original filename. | |
| last_name | No | Family name. | |
| asset_name | No | Asset type name (e.g. profile_pic). | |
| first_name | No | Given name. | |
| confirmation | No | Email or user ID confirmation for account close. | |
| content_type | No | MIME type. | |
| display_limit | No | How many items to return. Default 10, max 500. The MCP trims post-fetch; backend page_size stays MCP-internal so the platform cache stays warm. Applies to list-shares. | |
| email_address | No | Email address. | |
| invitation_id | No | Invitation opaque ID or key. | |
| content_base64 | No | Base64-encoded binary content. | |
| invitation_key | No | Invitation key. | |
| describe_action | No | When action='describe', narrow the output to ONE action's full params/notes (e.g. 'me'). Omit to get the compact action index. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already note destructiveHint=true and readOnlyHint=false. The description adds the specific information that the 'close' action is destructive, naming the exact operation. It also points to 'describe' for more detail, which is useful transparency about how to learn behavior. No contradiction with annotations.
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: two sentences that convey the tool's scope, the key action to invoke for reference, and the destructive hint. Every clause earns its place, with no redundancy or filler. The 'Destructive: close' note is specific and valuable.
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?
This is a complex multi-action tool with 19 parameters, no output schema, and broad capabilities. The description provides a high-level overview and defers to describe, which partially mitigates the lack of action-specific details. However, it omits return-value expectations and tool-selection guidance relative to siblings, leaving gaps for agent decision-making.
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?
All 19 parameters have complete descriptions in the schema (100% coverage), so the description does not need to elaborate on them. It adds the hint to use describe for a full action/param reference, which is helpful but does not materially enhance parameter understanding beyond the schema. 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 identifies the tool as covering user profile, contacts, invitations, and assets, which gives a clear resource scope. It lacks a specific verb for a single action but is appropriate for a multi-action hub. The instruction to call action='describe' helps the agent discover specifics, and the resource list differentiates it from sibling tools like 'invitation' and 'auth'.
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 no guidance on when to use this tool versus alternatives. The only directive is to call action='describe' for the full reference, which is a within-tool navigation aid, not a selection guideline. No exclusions or sibling comparisons are offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
workspaceAWorkspace management: list/details/update/delete, archive, members, notes, quickshares, share import, import toggle. NOTE: metadata actions MOVED — templates + AI extraction → metadata tool; node-level metadata → storage tool. The metadata-* actions here are deprecated one-release execute-and-warn shims, removed next release. Call action='describe' for the full action/param reference. Destructive: delete (workspace + all files). ⚠️ intelligence COSTS CREDITS (10/page) — only enable on explicit user request; toggle is rate-limited. Verbosity (detail param): list/available/members/list-shares default to terse (compact rows). details defaults to full (drill-down). Pass an explicit detail='standard'|'full' to override.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Search keyword(s). 1-1024 chars. Multi-token = ALL tokens (AND); case-insensitive; substring for ≤64 chars, else whole-word. | |
| keys | No | JSON array of metadata keys to delete (omit for all). | |
| name | No | Name. 1-255 (metadata-template-create, preview-match); 2-100 (metadata-template-update/-clone). Send "null" to clear on update. | |
| limit | No | Maximum number of items to return (1-500, default 100) | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| config | No | Saved-view config JSON: `{version:1, columns:[{field,visible?,width?}], sort:{field,dir}, filters:[{field,operator,value_type,value}]}`. Max 5 filters AND-chained; operator in `= != < <= > >=`; value_type in `string|int|float|bool`. | |
| detail | No | Per-entity verbosity for list/available/members/list-shares/details. Defaults: terse for list/available/members/list-shares, full for details. See action='describe' for per-level field lists. | |
| fields | No | JSON array of field defs. At least one field must have autoextract:true (default) or API returns 1605. Each: {name, description, type (string|int|float|bool|json|url|datetime), min?, max?, default?, fixed_list?, can_be_null?, autoextract?}. | |
| offset | No | Number of items to skip (default 0) | |
| org_id | No | Filter workspaces to this org. | |
| blob_id | No | Blob ID from POST /blob. Preferred for large note content (UTF-8 decoded). Single-use. | |
| confirm | No | Must match folder_name or numeric ID. | |
| content | No | Plain text/markdown. Notes: max 102400 bytes (100 KiB) — use blob_id for larger. | |
| node_id | No | Storage tree node opaque ID. Both files and folders are nodes — use this name regardless of which. | |
| archived | No | Filter by archive status (default "false"). | |
| blob_ref | No | Alias for blob_id (deprecated). | |
| category | No | Metadata template category. | |
| node_ids | No | JSON array of node IDs (1-25, same workspace; deduped server-side). Bulk metadata-get returns {format:'multi', objects, templates, errors}. | |
| order_by | No | Field key to sort metadata file list by. | |
| share_id | No | 19-digit numeric ID or custom name of share to import. | |
| note_name | No | Note filename (must end with .md). | |
| parent_id | No | Parent folder opaque ID or 'root'. | |
| perm_join | No | Who can join the workspace. | |
| key_values | No | JSON object of key-value pairs matching template fields. | |
| order_desc | No | Sort descending: 'true' or 'false'. | |
| description | No | Description. metadata-template-create: required, 0-1000 (empty allowed); metadata-template-update/-clone: 10-1000; preview-match/suggest-fields: 1-2000. Newlines allowed. Send "null"/"" to clear on update. | |
| folder_name | No | URL-safe workspace folder name (4-80 chars). | |
| template_id | No | Metadata template ID (e.g. mt_abc123). For metadata-search, restricts to nodes with values from this template (custom fields excluded). | |
| accent_color | No | Brand accent color JSON. "null" to clear. | |
| check_org_id | No | Org ID for check-name — suggests org-prefixed alternative if name taken. | |
| intelligence | No | Toggle AI features. ⚠️ COSTS CREDITS (10/page) — only enable on explicit user request. Disable flushes embeddings; re-enable re-indexes. Rate-limited. | |
| user_context | No | Short view/template hint (1-64 chars, letters/numbers/spaces). Example: "photo collection". | |
| workspace_id | No | Workspace opaque ID. Use this when only workspaces are valid (not shares or other contexts). For polymorphic contexts use profile_id. 19-digit numeric ID or custom name. | |
| display_limit | No | How many items to return. Default 10, max 500. The MCP trims post-fetch; backend page_size stays MCP-internal so the platform cache stays warm. Applies to list, list-shares, members, metadata-search. | |
| name_to_check | No | Folder name to check availability. | |
| owner_defined | No | Custom properties JSON. "null"/"" to clear. | |
| extract_fields | No | JSON array of field names to extract (e.g. `["vendor","amount"]`); omit/null for full row. | |
| parent_node_id | No | Destination folder opaque ID for TSV export (must be folder, not trashed). Omit for workspace root. | |
| describe_action | No | When action='describe', narrow the output to ONE action's full params/notes (e.g. 'list'). Omit to get the compact action index. | |
| template_filter | No | Filter for metadata template list. | |
| metadata_filters | No | JSON filter criteria for metadata file listing. | |
| background_color1 | No | Background color 1 JSON. "null" to clear. | |
| background_color2 | No | Background color 2 JSON. "null" to clear. | |
| perm_member_manage | No | Who can manage members. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint), the description details that delete removes 'workspace + all files,' warns that intelligence 'COSTS CREDITS (10/page)' and 'toggle is rate-limited.' It also explains verbosity defaults, giving concrete behavioral context. No contradiction with annotations.
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 dense single paragraph, front-loaded with a clear summary, but it repeats schema content (e.g., detail defaults, intelligence cost) and uses semicolons instead of cleaner structure. Each sentence contributes, but some redundancy makes it less concise than ideal.
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 44 parameters and no output schema, the description provides crucial context: migration notice for metadata actions, destructive delete warning, credit costs, and a pointer to `action='describe'`. It doesn't enumerate all return types, but the schema and describe action cover that, making this fairly 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 coverage is 100%, so all 44 parameters are already described in the input schema. The description repeats the `detail` param defaults and `intelligence` cost warning, but adds no new parameter information beyond what the schema already provides. 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 clearly states the tool's scope: 'Workspace management: list/details/update/delete, archive, members, notes, quickshares, share import, import toggle.' It distinguishes itself from sibling tools by noting metadata actions moved to `metadata` and `storage` tools, making its purpose unambiguous.
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 informs when not to use this tool: 'NOTE: metadata actions MOVED — templates + AI extraction → `metadata` tool; node-level metadata → `storage` tool.' Also directs to call `action='describe'` for the full action/param reference, providing clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
