Fast.io

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

Beyond annotations, it discloses side effects ('ask/status/chat-create/message-send consume credits'), destructive behavior ('Destructive: chat-delete'), read-only content guarantee, idempotency of chat-cancel, and default verbosity. Annotations only state readOnlyHint=false/destructiveHint=true, so the description adds substantial behavioral context without contradicting 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 dense but well-structured and front-loaded, moving from core purpose to usage guidance to side effects and per-action defaults. Every sentence carries new information, and the length is justified by 16 actions and 23 parameters.

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 high complexity and no output schema, the description covers read/write boundary, action categories, side effects, pagination caveats, and return shape for the primary action. It also points to action='describe' for full reference, making it complete for selection and initial 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%, and the description adds action-level semantics like detail defaults, aliases, and the ask return shape. However, most parameter-specific meaning already lives in the input schema, so the marginal addition is helpful but not dramatic.

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 names a specific role: 'MCP delegation surface over Fastio's RAG agent' that answers natural-language questions with citations and never mutates stored files, while explicitly managing chat threads/shares. This clearly distinguishes it from sibling primitive tools ('for content writes, call the primitive MCP tools directly').

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

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

It gives explicit direction: 'Prefer Ripley over issuing many primitive reads' and 'for content writes, call the primitive MCP tools directly,' plus lower-level chat/message actions for multi-turn control. A quick-start pattern ('action='ask' ... action='status'') makes when-to-use concrete.

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

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.

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

Annotations already declare destructiveHint=true, and the description adds specificity by listing exactly which actions are destructive: 'Destructive: api-key-delete, oauth-revoke, oauth-revoke-all.' It also points to the describe action for full details, which helps the agent understand 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 two sentences, front-loaded with the capability summary, an actionable pointer to describe, and a safety warning about destructive actions. 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?

Given the complexity (23 params, no output schema), the description handles completeness well by directing the agent to 'action='describe' for the full action/param reference' and explicitly listing destructive actions. It does not explain return values or workflows, but for a tool this broad, the describe pointer is a practical substitute.

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 parameter having a description. The description does not add additional parameter semantics beyond advising to use action='describe' for a full reference, which the schema itself already notes. Baseline 3 is appropriate since the schema carries the burden.

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 clearly states the tool's scope: 'Auth & sessions: signin, signup, signout, 2FA, PKCE, API keys, OAuth sessions.' This identifies the resource (auth/sessions) and the specific operations, distinguishing it from sibling tools that handle other domains like user or org. The verb is implicit in the action list but the domain is unmistakable.

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

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

The description gives clear context for when to use this tool (any authentication or session operation) and instructs to 'Call action='describe' for the full action/param reference.' It also flags destructive actions. However, it does not explicitly mention alternatives or when not to use it, so it falls 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.

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

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds specific behavioral insights: it names the destructive actions, discloses that the detail override is best-effort and may be a silent no-op, and explains the default verbosity modes for list/list-all versus details. This is valuable context that the annotations alone do not provide.

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

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

The description is compact and front-loaded: it states the core purpose first, then lists actions, destructive flags, and verbosity behavior in a tightly packed, well-structured manner. Every sentence adds value, and the caveat about the silent no-op is included without bloat.

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, no output schema), the description covers the essential behavioral aspects: purpose, action types, destructive operations, verbosity semantics, and a pointer to 'describe' for complete reference. It could go deeper on return values or all parameter interactions, but the 'describe' guidance mitigates that gap adequately.

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?

Although the schema already has 100% coverage with descriptions for every parameter, the description adds semantic context for the 'detail' parameter (defaults and override caveats) and points to 'describe' for full parameter reference. This enriches the otherwise schema-only information, though it does not need to repeat all parameter meanings.

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 what the tool does: 'Comments on files: add/list/delete/react, anchor to image regions, A/V timestamps, PDF pages, or text selections.' It specifies the resource (files/comments) and enumerates the supported actions, making it unambiguous and distinguishing it from sibling tools.

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 actionable usage guidance: it directs the agent to call action='describe' for the full reference, explicitly flags which operations are destructive (delete, bulk-delete), and explains the default verbosity behavior for the detail parameter. It does not explicitly name alternatives but gives clear internal guidance for using actions correctly.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description discloses that the tool consumes bandwidth credits, which is a significant cost consideration. It also flags the deprecated quickshare-details action and directs users to 'describe' for complete details. 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 sentences, front-loaded with the core purpose, then adding bandwidth and deprecation context, and a pointer to 'describe' for full reference. Every sentence earns its place with no fluff.

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 concise but sufficient for a complex tool given that the schema covers all parameters and the description points to action='describe' for the full reference. It omits return-value details, but the describe action mitigates this gap. The bandwidth credit note and deprecation warning add necessary context.

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 schema already explains every parameter. The description only mentions action values (file-url, zip-url, quickshare-details) that are already listed in the schema's enum, adding no deeper semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to download URLs for files, folder ZIPs, and quickshare links, with specific action names. It distinguishes itself from sibling tools like upload and fileshare by focusing on download links and explicitly marking quickshare-details as deprecated.

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 for when to use the tool and includes an explicit alternative for the deprecated quickshare-details action (use fileshare's create action). It also advises calling action='describe' for the full reference, but does not broadly contrast with all sibling tools (e.g., upload), though the name and description imply the distinction.

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

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

Goes beyond annotations by disclosing 'view-only dismiss/snooze', 'best-effort AI overlay', 'long-poll', and the limitation that only search/details honor output=, while summarize/activity-list/activity-poll are best-effort. These are behavioral traits not in the annotations, providing valuable transparency.

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 efficient, packing a lot of essential information about actions, verbosity defaults, and limitations into a compact form. While it's a long single paragraph, it earns its length given the tool's complexity, and avoids fluff.

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 and no output schema, the description provides a solid overview of core behaviors, including return granularity ('terse/standard/full') and poll-related parameters like cursor/lastactivity. It also points to 'describe' for full details, filling in gaps appropriately.

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%, but the description adds semantic context: it explains that detail defaults differ by action, gives the card_key format ('<lane>:<id>'), and describes the purpose of action='describe'. This adds meaning beyond the schema's own descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Event log and activity monitoring for workspaces and shares' and also surfaces the per-member DASHBOARD. It names specific actions (describe, search, summarize, etc.) and distinguishes its function from other tools by emphasizing its event/activity focus.

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 usage context: 'Call action='describe' for the full action/param reference', explains verbosity defaults and when to override with detail, and describes the behavior of activity-list/activity-poll (long-polling). Does not explicitly mention alternative tools or when not to use this tool, but context is strong.

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

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

The description adds substantial behavioral context beyond the annotations (readOnlyHint=false, destructiveHint=true). It explicitly states that delete is destructive but only removes the share, not the file; that grant-revoke is reversible; that passwords must be sent via header and never in URLs; and that gated shares require Authorization/password headers on direct URLs. This goes far beyond the simple annotation flags and is highly valuable for safe invocation.

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 each sentence earns its place: overview, action list, describe hint, binding immutability, uniform 404, password header, destructive/reversible behavior, and direct URL header requirements. It is well-structured with front-loaded summary and no fluff, despite being longer than average due to the tool's complexity.

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 16 parameters and no output schema, the description is remarkably complete. It covers the tool's purpose, all action categories, key behavioral constraints (uniform 404, password header, direct URL requirements), and points to 'describe' for further reference. The schema fully documents parameters, so the description complements it without unnecessary repetition.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that the `password` input is supplied via the x-ve-password header (never in URLs) and that the share binding is immutable. These details are not fully captured in the schema descriptions and are crucial for correct parameter handling.

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 Shares: durable single-file share links' and then lists the full range of operations (create/list/details/update/delete, grants, URLs). This clearly identifies the tool's purpose and distinguishes it from sibling tools like 'share' or 'upload' by emphasizing single-file binding and access management.

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 for when to use the tool: for creating durable file shares, managing per-user grants, and generating direct/preview/version URLs. It also provides behavioral guidance (e.g., 'deletion NEVER touches the bound file', 'Recipient 404 is UNIFORM') and instructs to call action='describe' for the full reference. However, it does not explicitly name alternative tools or specify when NOT to use this tool.

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

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

Annotations already indicate readOnly and non-destructive behavior, and the description adds valuable context: results are grouped into independently paginated buckets with health reports, the metadata bucket is workspace-only, and a single query is searched across all applicable buckets. This goes well beyond the structured 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 every sentence earns its place: it states the core purpose, highlights grouped buckets and pagination, gives usage guidance with explicit alternatives, and notes the code-mode distinction. It is front-loaded with the primary function and avoids repetition of schema content.

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

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

Given the tool's complexity (16 params, no output schema), the description is remarkably complete. It explains the grouped result structure, per-bucket pagination, workspace/share differences, and how to obtain the full parameter reference. The schema already documents all parameters, so the description fills the remaining contextual gaps.

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

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

The schema descriptions already cover 100% of the 16 parameters, so the baseline is 3. The description adds value by clarifying that a single query searches across all buckets and directing users to action='describe' for the full parameter reference, which helps with the many alias parameters. It does not introduce any new param details, but the coverage is already complete.

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 this is a "Unified search across a workspace or share" that groups results by type into buckets, using the verb "search" with a specific resource. It explicitly distinguishes itself from sibling tools by calling itself the "grouped SUPERSET" and naming the narrower alternatives (`storage action=search`, `metadata action=search`, code-mode `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?

The description explicitly tells the agent when to use this tool (for grouped results across multiple types) and when not to (prefer narrower tools for a single result type). It also directs the agent to call action='describe' for the full action/param reference, and warns that the code-mode search tool targets the API catalog, not content.

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

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

No annotation contradiction; readOnlyHint=true is reinforced by the explicit statement that it 'performs NO platform action'. The description goes well beyond annotations by explaining the output is guidance text, answers are grounded in Fastio's knowledge, it's free, and requires only auth. This fully discloses behavior without needing additional inference.

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

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

The description is front-loaded with the core purpose in the first phrase. It contains some repetition (EXPLAIN-ONLY / ADVISORY vs. performs NO platform action), but every sentence contributes distinct useful information. It's structured logically, moving from function to safety to alternatives to access constraints.

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

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

Given there is no output schema, the description fully covers what the agent should expect: grounded guidance text or a clarifying question. It also explains the action enum, the distinction from `ai`, and authentication requirements. For a natural-language help tool, this is complete and self-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 covers all parameters thoroughly (100%), so baseline is 3. The description adds extra meaning by detailing the 'describe' action for full reference and clarifying that questions should be specific natural-language queries about Fastio, and that answers suggest concrete tool calls. This enriches parameter understanding beyond the schema alone.

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 a specific verb+resource: 'ask a natural-language 'how do I…' question about Fastio'. It distinguishes itself from siblings by explicitly contrasting with the `ai` tool for RAG and emphasizing it's about Fastio itself. The phrase 'Built-in product help' also clarifies its role.

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 names an alternative (`ai` tool for file RAG) and tells the agent to prefer this tool over guessing endpoints. It also advises 'read the guidance, then act with the other tools', giving clear when-to-use and when-not-to-use context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds that 'delete' is destructive, which is useful context, but does not disclose other behavioral details such as reversibility of revoke or side effects. There is no contradiction between description and 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 sentences, front-loaded with purpose, a pointer to deeper docs, and a safety warning. Each sentence earns its place with no wasted words.

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

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

The tool has 10 parameters and multiple actions with no output schema. The description gives a brief overview and points to action='describe' for the full reference, which partially compensates for missing information. However, it does not explain return values, action-specific behavior nuances, or the meaning of list vs list-by-state, so completeness is moderate.

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%—every parameter has a description. The description adds a pointer to action='describe' for full parameter reference, but does not explain individual parameters beyond the schema. Thus it meets the baseline but does not elevate it.

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's resource (workspace/share invitations) and operations (list, filter by state, update, revoke). It also notes the destructive delete action. This distinguishes it from sibling tools by focusing on the invitation lifecycle.

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 for managing invitations ('Workspace/share invitations: list, filter by state, update, revoke') and suggests using action='describe' for full reference. However, it does not explicitly compare with alternatives or state when not to use this tool, so only implied usage guidance is present.

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

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

Annotations already indicate destructiveHint=true, and the description adds 'Destructive: remove,' clarifying which action is destructive. This is useful but minimal; it does not discuss reversibility, permissions, or side effects, though annotations lower the 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?

Two sentences cover scope, actions, a meta-instruction, and destructiveness. No waste—front-loaded and readable.

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

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

For a 20-parameter multi-action tool, the description is intentionally brief but compensates by directing users to the 'describe' action for full reference. It leverages annotations and schema to cover safety and parameter details, making it reasonably complete despite no output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description's pointer to 'describe' duplicates the action parameter's own description, so it adds no additional parameter meaning 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 clearly states the tool manages workspace/share members with specific actions: list, add, remove, update, transfer ownership, join, leave. It includes the resource scope (workspace/share) and differentiates from sibling tools like workspace, share, and invitation.

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 mentions 'Call action='describe' for the full action/param reference', which provides a way to discover usage. However, it does not explicitly state when to use this tool versus alternatives or provide exclusions for overlapping sibling tools.

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

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

The description goes well beyond annotations by naming the destructive actions ('template-delete, view-delete, nodes-remove'), listing credit-consuming actions ('preview-match, suggest-fields, auto-match, extract-all — each spends AI credits'), and adding server-side caveats like 'category accepted but ignored server-side' and the autoextract:true requirement (API returns 1605). This is rich, actionable behavioral context.

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?

Despite the tool's complexity, the description is a tight 5-sentence overview: purpose, pipeline, describe pointer, storage alternative, and risk flags. Every sentence carries essential info with no filler, and it is front-loaded with the core purpose.

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-parameter, multi-action tool with no output schema, this description gives a sufficient mental model: scope, capability map, key exclusions, destructive/credit side-effects, and a direct 'describe' escape hatch for exhaustive details. 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 every parameter. The description itself adds minimal parameter-level semantics beyond summarizing the action families, so the baseline of 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 opens with a specific domain phrase: 'AI metadata templates & extraction (the unstructured-data automation pipeline)' and enumerates the major capability groups (template CRUD/clone, assign/resolve, AI pipeline, saved views, lexical search). It clearly distinguishes from siblings by explicitly moving node-level metadata to 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?

It gives explicit when/where guidance: 'Node-level metadata (get/set/delete/extract on a single file) lives on the `storage` tool' — a direct alternative. It also outlines the AI pipeline sequence and points to action='describe' for full reference, helping the agent pick the right action and know side effects (AI credits) before invoking.

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

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

The description explicitly warns that 'close (permanently deletes org and all data)', which adds specific destructive behavior beyond the generic destructiveHint=true annotation. It also reveals the 'describe' mechanism, indicating a self-documenting structure. No behavior contradicts the annotations (readOnlyHint=false, openWorldHint=true, 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?

The description is three concise sentences: a purpose statement, a usage pointer, and a critical destructive warning. It is front-loaded with the tool's scope, immediately provides actionable guidance, and includes a safety note. 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?

For a tool with 58 parameters and dozens of actions, the description is intentionally a high-level entry point. It covers the essential context—what the tool manages, how to get the full reference via 'describe', and the key destructive caveat. While it does not enumerate every action or return value, the 'describe' pointer compensates for the lack of an output schema and the huge parameter space, making it sufficiently complete for an agent to proceed.

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 provides 100% parameter descriptions, so the description need not repeat them. The note 'Call action='describe' for the full action/param reference' directs the agent to the schema for detailed parameter meaning. The description adds no extra parameter semantics beyond what the schema offers, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as 'Organization management' and enumerates its scope (CRUD, billing, members, invitations, ownership transfer, assets, discovery, custom domains). While the verb 'management' is broad, the resource and domain list give a concrete sense of purpose. It does not explicitly differentiate from sibling tools like 'member' or 'invitation', but the scope list helps distinguish it as the overarching organization 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?

Usage is implied through the listed domains (CRUD, billing, members, etc.), and the instruction to 'Call action='describe'' provides a clear first step for the agent. However, there is no explicit guidance on when to prefer this tool over siblings like 'member', 'invitation', or 'asset', nor any exclusion criteria. The describe hint is useful but does not fully replace when-to-use versus alternatives.

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

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

Beyond annotations (destructiveHint=true), the description adds critical behavioral details: idempotency of create per (workspace, topic_slug), presence refresh on any call (liveness ≠ progress), and file handoff via upload. This significantly aids agent understanding of side effects and constraints.

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

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

The description is well-structured with a clear front-loaded purpose statement. It includes additional guidelines succinctly. It is not overly verbose, but slightly longer than strictly necessary due to detailed behavioral notes.

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 complexity (21 parameters, 11 actions) and absence of output schema, the description covers key behaviors and directs users to the 'describe' action for full protocol. It is reasonably complete for an overview, though edge cases like parameter validation are left to the schema.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add parameter-specific meaning beyond what is already in the input schema descriptions. For example, it does not explain 'agent_label' or 'status_version' further.

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: 'Coordination 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.' It uses specific verbs and resources, and the room concept is distinct from sibling tools like 'fileshare' or 'upload'.

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 for when to use the tool (for coordination rooms) and mentions complementary tools ('Hand files off via the `upload` tool'). It also suggests using action='describe' for full protocol. However, it does not explicitly exclude alternatives or state when not to use this tool, so it misses the highest score.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=true. The description supplements this by specifying that delete is permanent, that autotitle consumes credits and mutates share metadata, and that intelligence on create costs 10 credits/page and defaults to false. These behavioral details go well beyond the annotations and help the agent anticipate side effects.

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

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

The description is dense but well-organized: summary, deprecation notice, self-service reference, side effects, cost warnings, and verbosity defaults. Every sentence conveys a distinct, actionable fact, and the use of bullet-like formatting and emojis improves scanability without padding.

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?

With 41 parameters and 15 actions but no output schema, the description cannot fully document every behavior. However, it provides a strong orientation: action families, destructive operations, side effects, credit costs, verbosity defaults, and a pointer to the built-in `describe` action for exhaustive per-action reference. This makes it complete enough for an agent to start using the tool safely.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds cross-action semantics for the `detail` parameter, explaining terse/standard/full defaults per action and the override syntax. It also reinforces the cost implication of `intelligence` and the deprecation of `quickshare-create`, which informs parameter choice. This adds modest value over 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 'Share management: create/update/delete, archive, password auth, members, autotitle,' which clearly identifies the tool's broad scope and key operations. It also distinguishes from the sibling `fileshare` tool by noting the deprecated quickshare-create and directing users to fileshare's create action. This makes the purpose specific and differentiated.

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

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

The description provides explicit usage guidance, including a deprecation notice with error code 10756 and a recommendation to use the `fileshare` tool's create action for durable single-file shares. It instructs users to call action='describe' for the full action/param reference, and it explains default verbosity per action with an override. It also warns about credit costs for intelligence, giving clear when-to-use context.

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

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

Annotations already signal destructiveHint and readOnlyHint, and the description adds concrete destructive semantics: 'purge (irreversible)', 'delete moves to trash', and 'metadata-delete removes metadata keys'. It also explains default verbosity behavior for different actions, going beyond the generic annotation flags.

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

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

The description is compact and front-loaded: it states the scope, lists operations, points to the describe action, and then covers safety and verbosity. Every sentence carries essential information and there is no filler.

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

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

For a tool with 50 parameters and over 29 actions, the description cannot fully document everything, but it covers the highest-risk behaviors (destruction), verbosity defaults, and provides a clear escape hatch through action='describe'. Combined with thorough schema descriptions, this is reasonably complete, though it does not describe return shapes or all polymorphic context-id patterns.

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 describes all 50 parameters with 100% coverage, so the description does not carry the burden of documenting them. It does add value by explaining the detail parameter defaults and the action='describe' mechanism, but this is supplemental rather than necessary, matching the baseline of 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 ('Files & folders on workspaces/shares') and enumerates concrete operations (list, search, copy, move, delete, rename, trash, transfer, versions, locks, previews, metadata). It is specific about the resource domain, though it is a broad multi-action tool and does not explicitly contrast with sibling tools like fileshare or metadata, so it stops short of a 5.

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

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

The description implies usage through its list of operations and gives helpful pointers like 'Call action='describe'' for the full reference. It also provides behavioral cautions around destructive actions and verbosity defaults, but it does not explicitly say when to prefer this tool over sibling tools 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.

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

Beyond the destructiveHint annotation, the description discloses side effects (creates files, consumes storage credits), same-name overwrite as recoverable versions, exact filesize mismatch causing failure code 10522, and max_size aborting mid-transfer. This is rich behavioral context that annotations do not provide.

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 justified by the tool's complexity (40 params, 20 actions). It is well-structured with uppercase section headers and dense, front-loaded content. Every sentence carries operational value, though a slightly more compressed format would improve scannability.

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 this complex with no output schema, the description is remarkably complete: it covers all upload modes, side effects, overwrite/versioning, transport limits (100 MB vs few MB), fallback paths, and file size constraints. It also points to action='describe' for deeper per-action reference, making it a sufficient entry point.

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, but the description adds cross-parameter decision guidance: prefer blob_id over content_base64, content is text-only, filesize must match exactly, max_size should be overestimated. It reinforces and prioritizes schema descriptions, providing strategic meaning beyond each parameter's individual doc.

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:' and immediately enumerates four distinct methods (stream-upload, chunked, web import, batch), clearly defining the tool's purpose and scope. It differentiates internal actions enough to make the tool's capabilities obvious, even without naming sibling tools.

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, prioritized decision tree: 'read top-to-bottom, pick the FIRST that matches,' with precise conditions for web-import, POST /blob + stream-upload, content_base64 fallback, and chunked sessions. It also includes strong exclusions like 'Do NOT guess filesize' and 'fall back only when you cannot reach /blob.'

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

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

Annotations already indicate destructive behavior, and the description adds specificity by highlighting 'Destructive: close.' This goes beyond the structured data by naming which action is destructive. A minor gap is that 'asset-delete' is also destructive but not mentioned, though this doesn't contradict 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 concise sentences: scope, reference pointer, and destructive flag. Each sentence earns its place, and the most important guidance is front-loaded. No wasted words.

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

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

Given the tool's complexity (17 actions, 19 params) and the lack of an output schema, the description directs to 'describe' for full details, which mitigates the sparse top-level text. The schema is rich and self-describing, making the description sufficient for orientation. It could be more complete by explicitly noting the multi-action umbrella structure and highlighting other destructive actions, so not a 5.

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

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

Schema coverage is 100%, and every parameter has a descriptive definition, so the baseline is 3. The tool description itself doesn't add parameter-level meaning beyond the pointer to 'describe' for the full reference, which is an instruction rather than semantic detail.

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 covers user profile, contacts, invitations, and assets, and directs to 'describe' for full action reference. It distinguishes by user-centric scope, but doesn't explicitly differentiate from overlapping sibling tools like 'invitation' or 'asset', preventing a 5.

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

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

It provides clear context for when to use this tool (user-related operations) and instructs calling action='describe' for the full action/param reference. It also flags the destructive 'close' action. However, it does not explicitly name alternative sibling tools or exclusions, so it falls 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.

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

Annotations only say readOnlyHint=false and destructiveHint=true, but the description adds specifics: delete removes workspace and all files; intelligence costs 10 credits/page, is rate-limited, and requires explicit user consent; metadata-* actions are deprecated one-release execute-and-warn shims. It also discloses verbosity defaults and override behavior. No contradictions.

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

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

The description is dense but every sentence serves a purpose: operation list, deprecation notice, destructive warning, cost warning, and verbosity defaults. It's front-loaded with the most critical info. While long, it's appropriate for a 44-parameter 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?

For a multi-action tool with no output schema, the description covers the main action groups, points to `action='describe'` for exhaustive references, and highlights safety-critical constraints (destructive delete, credits). It's sufficiently complete for an agent to navigate the tool.

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 value by explaining the `detail` parameter's default modes (terse vs full) and the `intelligence` parameter's credit cost and rate limit – details not fully captured in the schema. This lifts it to a 4.

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 'Workspace management: list/details/update/delete, archive, members, notes, quickshares, share import, import toggle' – a specific resource with enumerated operations. It explicitly distinguishes from the `metadata` and `storage` tools by noting metadata actions moved there, and flags deprecated shims. This clearly separates it from sibling tools.

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 explicit when-not guidance: metadata actions belong to the `metadata` tool and node-level metadata to `storage` tool. It also instructs to call `action='describe'` for full reference, and warns to only enable intelligence on explicit user request. This is strong usage guidance with alternatives.

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