Proton Drive MCP

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context: clarifies that operations fail after logout, and explicitly states idempotency. It does not 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?

Four sentences, all essential. Core action is front-loaded. No wasted words. Clearly structured.

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

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

For a zero-parameter tool with clear annotations, description fully covers purpose, usage, effects, and idempotency. No 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?

No parameters. Baseline score of 4 is appropriate; description does not need to add parameter information.

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 uses specific verb 'clear' and resource 'stored Proton Drive session'. It clearly states the tool's action and distinguishes it from siblings by noting that after logout all file and sharing operations fail.

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 states when to use ('on shared machines to prevent session persistence') and when not to use ('Do not call during an active workflow'). Also mentions the consequence (breaks subsequent drive_* calls) and idempotency, providing complete usage guidance.

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=true and idempotentHint=true, but the description adds deeper behavioral context: it explains the underlying CLI has no dedicated status command, that probing by resolving /my-files makes a real (lightweight) call, and that it does not expose the account email. This goes beyond annotations and helps the agent anticipate side effects and limitations.

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, each earning its place: purpose/return, implementation detail (probe via /my-files), and usage guidance. It is front-loaded with the core purpose and avoids redundancy with schema or annotations.

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 0-parameter tool with strong annotations and an explicit return description, this is fully complete. It covers what the tool does, how it works, when to use it, and a key limitation (no email exposure). No important context is missing.

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

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

The tool has zero parameters and the schema coverage is 100% (vacuously). The description adds no parameter detail because none exists. Per the rubric, 0 parameters yields a baseline of 4, and the description appropriately avoids inventing parameters.

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

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

The description starts with a specific verb+resource: 'Check whether the Proton Drive CLI has an active authenticated session.' It clearly distinguishes the tool from siblings by explaining it is the auth-status check, and it also specifies the return shape ({authenticated: boolean}). This is unambiguous and unique among the listed drive_* 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?

Explicit guidance is provided: 'Use before any file operation when you need to confirm the session is valid — all other drive_* tools (except drive_version) require authentication.' This states when to use it and implies when not to (before drive_version). It also notes the CLI lacks a dedicated status command, so the probing behavior is explained.

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 beyond the annotations (idempotentHint: false, destructiveHint: false) by adding that authentication is required, emphasizing the original is preserved (not a move), and warning about storage costs for large folder trees. These are valuable behavioral traits not present in 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 four sentences, each adding meaningful information: the core function, authentication, non-move behavior, and usage caution. It is front-loaded with the purpose and contains no redundant wording.

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

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

For a 2-parameter tool with no output schema, the description covers purpose, usage, authentication, and a caution. It does not specify what happens if the destination path already exists or what the response format is, leaving a minor gap, but the overall context is strong.

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?

Both parameters have comprehensive schema descriptions with examples, covering 100% of the schema. The tool description adds no additional parameter semantics, so the baseline score of 3 applies due to 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 copies a file or folder to another location on Proton Drive, using the specific verb 'copy' and resource. It explicitly differentiates from the sibling drive_move by stating 'the original is preserved — this is not a move,' making the 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?

It provides explicit when-to-use guidance: 'Use drive_move when you want to relocate without keeping the original' and a warning against duplicating large folder trees due to storage cost. This covers both when to use and when not to use, naming the alternative tool directly.

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 irreversibility, authentication requirements, rejection of live paths, the confirmed=true requirement, and instructs to always show the exact path and get explicit confirmation. These are significant behavioral traits not present in 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 front-loaded with the core purpose and irreversibility flag, then covers prerequisites, alternatives, and safety. Every sentence adds value; no filler or 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?

For a destructive tool with no output schema, the description covers the operation's purpose, prerequisites (must be in trash), alternatives, required confirmation, and safety signal. It is complete for an agent 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?

Schema coverage is 100%, giving baseline 3. The description adds meaning by clarifying that 'path' must be a trash path (not a live one) and that 'confirmed' must be true, plus the instruction to show the path to the user. This elevates the parameter 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 states a specific verb and resource: 'Permanently delete a file or folder that is already in the Proton Drive trash'. It clearly distinguishes from siblings like drive_trash (moves to trash) and drive_empty_trash (clears all trash) by scoping to already-trashed items.

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: 'Use drive_trash first to move a live item into trash, then pass its trash path here — or drive_empty_trash to clear everything at once.' It also states that live paths are rejected, and requires confirmed=true, providing 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?

With only openWorldHint in annotations, the description carries the full behavioral burden and fully delivers: it explains the destination-folder semantics, automatic folder creation, original-name preservation, recursive folder downloads, file/folder conflict defaults, version-specific behavior, and that the return value is {downloaded} not the path. No contradictions 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?

Though long, the description is dense and every sentence earns its place: purpose, critical path semantics, example, recursion, conflict defaults, return-value caveat, and exclusions. Critical info is front-loaded before the caveats.

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 no output schema and sparse annotations, the description is remarkably complete: authentication, path construction, recursive behavior, conflict strategy defaults, return type, version context, and clear routing to sibling tools. An agent has everything needed to call correctly and interpret results.

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

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

Schema coverage is 100% and the schema already documents localPath and conflict strategies well. The description still adds value with a concrete example (/my-files/report.pdf + /tmp/out → /tmp/out/report.pdf) and clarifies that conflict strategies are set separately for files and folders with default 'skip'.

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

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

The description opens with a specific verb and resource: 'Download a file or folder from Proton Drive to the local filesystem.' It clearly distinguishes itself from similar operations by explicitly naming drive_move and drive_read_file as alternatives for different tasks.

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 (downloading to local filesystem) and when-not-to-use guidance: 'Do not use to move files within Drive (use drive_move) or to read a small text file's contents (use drive_read_file if PROTON_DRIVE_SYNC_PATH is set).' It also notes the authentication requirement.

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 set destructiveHint=true; description adds critical details: irreversible, no recovery, and requires explicit confirmation. Provides workflow guidance beyond 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?

Two sentences, front-loaded with key action and constraints, 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?

Complete for a simple tool with one parameter: covers purpose, prerequisites, safety, workflow, and alternatives. No output schema needed.

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%; the description adds context that confirmed must be true after user review, reinforcing the safety requirement beyond the schema's 'Must be true'.

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 permanently deletes all trash items, is irreversible, and distinguishes from individual deletion tools like drive_delete and drive_trash.

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 states when to use (after listing trash and getting user confirmation) and when not to (for specific items, use siblings). Also lists prerequisites: authentication and confirmed=true.

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=true and idempotentHint=true, but the description adds valuable context: requires authentication and warns that 'the exact shape is not guaranteed.' This goes beyond safety/read-only to set return-format expectations, which is not conveyed by 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 concise sentences: the first states the purpose, the second explains return richness and caveat, the third gives exclusion guidance. Each sentence earns its place, no redundancy, and the most important information is front-loaded.

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

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

For a simple, read-only single-path tool with no output schema, the description covers all necessary context: what it does, when to use it, how the output behaves, and what not to use it for. It is fully self-contained for an agent to decide 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?

The schema has 100% coverage for the single 'path' parameter, including a clear description with an example and format constraint. The tool description does not add further parameter specifics beyond what the schema already provides, 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 states exactly what the tool does: 'Get full metadata for a single Proton Drive file or folder, including latest revision details.' It uses a specific verb (get) and resource (single file/folder) and explicitly differentiates from drive_list by noting it returns richer data ('raw CLI node object').

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 explicit when-to-use: 'Use when you need details drive_list doesn't return (e.g. revision info) for one specific known path.' Also gives a clear when-not-to-use with an alternative: 'Do not use to enumerate a folder's children — use drive_list instead.' This meets the highest standard.

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 provide destructiveHint=false, so the description adds value by stating authentication requirements, the outcome (folder becomes accessible), and the caution to always fetch the uid from drive_list_invitations. This goes beyond the annotation and gives useful 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?

The description is three sentences, front-loaded with the purpose, and every sentence serves a clear function: stating the action, mentioning authentication, giving instructions, and warning against guessing. No wasted words.

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

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

For a simple one-parameter tool, the description covers prerequisites, authentication, outcome, and a caution. It doesn't explain error cases or edge conditions, but given the absence of an output schema and the low complexity, it is 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?

The schema already describes the uid parameter as 'Invitation UID from drive_list_invitations output' with examples, providing 100% coverage. The description reinforces this by saying not to guess the uid, but it doesn't add new semantic information beyond the schema, 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 states the tool's function: 'Accept a pending Proton Drive sharing invitation.' It uses a specific verb ('accept') and resource ('sharing invitation'), and it distinguishes itself from sibling tools like drive_invitation_reject and drive_list_invitations.

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

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

The description provides explicit guidance on when to use this tool by instructing to get the invitation uid from drive_list_invitations first. It also warns against guessing the uid, reinforcing the prerequisite. It doesn't explicitly mention alternatives like reject, but the context is clear enough.

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 adds valuable context: the rejection is permanent, the sender is not notified, and authentication is required. This gives the agent a full understanding of the action's consequences.

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 with zero redundancy: the first states the action, the second provides the prerequisite, and the third adds crucial side effects. Front-loaded and efficient.

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 simplicity (one parameter, no output schema), the description covers purpose, prerequisite, and consequences. The destructiveHint annotation handles the safety profile, making the description complete for its complexity.

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

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

The schema already provides 100% coverage for the uid parameter, including its provenance and examples. The description reinforces the 'do not guess' rule but does not add new semantic meaning beyond what the schema states, 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 uses the specific verb 'Reject' with the resource 'pending Proton Drive sharing invitation,' making the tool's function unmistakable. It also distinguishes from sibling tools like drive_invitation_accept and drive_list_invitations.

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

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

Explicitly instructs the user to obtain the uid from drive_list_invitations first and warns against guessing the uid. This provides clear when-to-use and prerequisite guidance, with explicit exclusions for guessing.

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 provide readOnlyHint and idempotentHint. The description adds behavioral context: requires authentication, returns a specific structure, clarifies non-recursive behavior. No contradictions 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?

Every sentence earns its place. Front-loaded with the core action and resource. No redundancy or filler. Efficiently conveys purpose, usage, return format, and alternatives in under 50 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 simplicity (1 param, no output schema), the description is complete. Explains return format, scope (non-recursive), gives concrete use cases, and directs to relevant siblings. No gaps for an agent 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?

Schema coverage is 100% for the single 'path' parameter. The description adds meaning: 'Absolute remote Drive path (must start with '/')' and provides examples like '/my-files' and '/my-files/Reports'. This goes beyond the schema's basic description.

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?

Clearly states 'List the immediate children of a Proton Drive folder' – a specific verb ('List') and resource ('immediate children of a folder'). Differentiates from siblings by noting it is not recursive and does not list trash.

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 provides when to use: 'Use before drive_upload to confirm the destination exists, or before drive_download to verify the remote path.' Also states when not to use: 'Do not use to list trash — use drive_list_trash instead.' Offers clear 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?

Annotations already declare read-only and idempotent behavior. The description adds useful context: requires authentication and details the return structure including fields like uid, role, invitedByEmail, nodeType. It also clarifies the scope to 'pending' invitations. This goes beyond annotations without 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?

Every sentence earns its place: purpose, auth requirement, return format, and a workflow/differentiation note. The description is compact, front-loaded, and free of redundant content.

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

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

For a zero-parameter, read-only list tool with no output schema, the description fully covers what the agent needs: what it lists, auth needs, the return shape, and how the result should be used. It also clarifies edge cases (not for folder membership) to prevent misuse.

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 tool has zero parameters, so the baseline is 4. The description adds meaning by explaining the return structure, which is relevant since no output schema is provided. There are no parameter details to clarify.

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: 'List all pending sharing invitations from other Proton Drive users' with a specific verb and resource. It also distinguishes itself from siblings by explicitly directing users to drive_share_status for folder members.

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 explicit when-to-use guidance for listing pending invitations and when-not-to-use with a named alternative ('Do not use to list members of folders you own — use drive_share_status instead'). It also explains the workflow of using the returned uid with drive_invitation_accept/reject.

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 provide readOnlyHint and idempotentHint. The description adds that it requires authentication and specifies the return format, going beyond annotations. 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 four sentences that are all relevant, front-loaded with the main purpose. Slightly wordy but efficient overall.

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

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

For a zero-parameter, read-only tool, the description covers purpose, return format, prerequisites, and usage context. No gaps given the absence of 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?

No parameters in the schema, and schema coverage is 100%. Description adds no parameter info, but per guidelines, baseline 4 for zero parameters.

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

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

The description clearly states 'List all files and folders currently in the Proton Drive trash' with a specific verb and resource, and distinguishes from siblings by explicitly noting not to use for active files.

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 states when to use the tool (before drive_restore or drive_empty_trash) and when not to use it (use drive_list for active files).

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?

Discloses authentication requirement, failure conditions (folder exists or parent missing), and behavior (no intermediate directories) beyond the destructiveHint annotation.

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 front-loaded with purpose and authentication, then constraints; 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?

With one parameter, no output schema, and minimal annotations, the description fully covers preconditions, failures, and exclusions.

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?

Adds meaning beyond schema: clarifies that path must be absolute, starts with '/', provides example, and covers the single parameter's constraints.

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 creates a new empty folder on Proton Drive, distinguishes from sibling tools like drive_upload and explicitly mentions it does not create nested trees.

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 explicit when-to-use (creating folders) and when-not-to-use (uploading files, creating nested trees in one call) with a suggestion to check existence via drive_list.

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 (false), the description discloses that authentication is required, that the operation fails if the destination path is already occupied or its parent folder does not exist, and explains the exact rename/move mechanics. While it does not mention return values, there is no output schema and the provided context is sufficient for safe usage.

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 well-structured paragraph: it starts with the core action, then explores rename and move patterns with a concrete example, lists failure conditions, and closes with explicit 'do not use' alternatives. Every sentence serves a distinct purpose, with no filler or 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 tool has only two parameters, both thoroughly documented in the schema, and no output schema, the description covers all necessary operational context: authentication prerequisite, usage modes (rename/move), failure conditions, and exclusions. An agent has enough information to select and invoke this tool correctly in any relevant scenario.

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?

Even though both schema parameters have descriptions (100% coverage), the tool description adds practical semantics that shape parameter usage: renaming requires keeping the same parent while changing the filename, moving requires a different parent. This clarifies how to construct sourcePath and destinationPath for each intended operation, exceeding what the schema alone provides.

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

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

The description opens with a specific verb and resource ('Move or rename a file or folder on Proton Drive'), immediately clarifying the tool's core function. It also distinguishes itself from siblings by explicitly referencing drive_rename, drive_copy, and drive_download, making the 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?

Provides explicit when-to-use guidance: details the rename scenario (same parent, change filename) versus the move scenario (different parent), and directs users to drive_rename for pure renames, drive_copy for copies, and drive_download for downloads. It also states a prerequisite (parent folder must exist) and failure conditions, giving clear operational boundaries.

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 readOnlyHint annotation, the description adds critical behavioral details: requires environment variable, synced local file, text only, size limit, and error handling for non-text or oversized files. 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?

Efficient and well-structured: first sentence states purpose, followed by prerequisites, constraints, and alternatives. No extraneous text.

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 simplicity (one parameter, no output schema), the description covers all necessary context: what it does, prerequisites, limitations, and alternative tools. It is fully sufficient for an agent to use correctly.

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

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

The schema has 100% coverage with a clear description of the 'path' parameter. The tool description adds context about the environment variable and mapping to local folder, but does not significantly expand on parameter details 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?

Describes exactly what the tool does: read text contents of a synced file. Distinguishes itself from the sibling drive_download by specifying it is only for text files under 1 MB.

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 states when to use (text files under 1 MB, synced locally) and when not to use (binary, over 1 MB, not synced), providing the alternative drive_download. Also lists prerequisites (env variable, app running).

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 'Requires authentication,' which is not in the annotations (only destructiveHint: false). It also discloses that the operation is in-place and cheaper than drive_move. However, it does not mention potential conflict behavior or error conditions; the sparse annotation means the description carries more burden, but the added context is still valuable.

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, each earning its place: purpose, cost/equivalence, and explicit usage direction. It is front-loaded, concise, and free of 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?

For a simple two-parameter rename tool with no output schema, the description covers the core action, authentication, equivalence, and usage boundaries. It could mention what happens on overwrite or error, but the level of detail is adequate for a low-complexity 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?

The input schema covers both parameters with descriptions (100% coverage). The description reinforces that newName is just the name and path is absolute, but it doesn't add semantic detail beyond what the schema already provides. 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 states exactly what the tool does: 'Rename a file or folder in place on Proton Drive, without moving it to a different parent folder.' It uses a specific verb and resource, and explicitly differentiates from drive_move by clarifying the in-place constraint and equivalency.

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 guidance: 'Do not use to relocate to a different folder — use drive_move for that (or when unsure which applies).' It also explains when this tool is preferable ('cheaper — one CLI call'), giving the agent explicit decision criteria.

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: false annotation, it adds authentication requirement, failure cases, and that it restores to original path. Could mention return value but still strong.

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

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

Four concise sentences, front-loaded with purpose, no unnecessary 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?

Covers prerequisites, conditions, and limitations. Lacks explicit return value but sufficient for a simple restore tool with 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?

Description explains how to obtain the path parameter via drive_list_trash and that it must start with '/', adding value beyond the schema's description of the parameter.

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

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

The description clearly states the tool restores a trashed file or folder to its original path, distinguishing it from sibling tools like drive_trash, drive_list_trash, and drive_delete.

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

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

Explicitly instructs to use drive_list_trash first, specifies that it only works for trashed items, and warns of failure conditions (missing parent folder, name conflict).

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 discloses key behavioral traits beyond the minimal annotation (openWorldHint): it immediately sends an email notification and warns that duplicate invitations may silently overwrite roles. With no other annotations, this provides essential transparency for a mutation tool.

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

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

The description is well-structured with the core purpose first, followed by warnings and usage notes. It is slightly longer than necessary but every sentence adds value. 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?

Despite lacking an output schema, the description covers the tool's action, prerequisites (run drive_share_status first), side effects (email sent, potential overwrite), and role explanations. This is complete information for an agent to use the tool correctly.

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

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

Schema coverage is 100% and the schema already provides detailed descriptions for all parameters including enum values. The description reiterates the role meanings but does not add substantial new semantic information beyond what is in the schema.

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

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

The description uses a specific verb-resource pair ('Invite a person to access a Proton Drive file or folder by email') and distinguishes the tool from siblings like drive_share_status and drive_share_revoke by referencing them explicitly.

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 when-to-use and when-not-to-use guidance: 'Do not call without first running drive_share_status — duplicate invitations may silently overwrite the existing role.' It also instructs to confirm email and role with the user before calling, and mentions an alternative tool for removal.

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 annotation destructiveHint=true already signals destructive behavior. The description adds valuable context by explaining that the action only removes your access and does not affect the owner or other members. It also notes authentication requirements, providing transparency beyond the annotation without contradicting it.

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 long, front-loaded with the primary action, and each sentence earns its place by adding either the action, exclusions, or alternative tool guidance. No unnecessary information is present.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, exclusions, and behavioral effects. It also distinguishes from the most relevant sibling (drive_share_revoke), making the context complete without needing additional details.

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%, and the parameter 'path' is already well-documented in the schema with format and example. The tool description does not add additional meaning beyond the schema, so the 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 states the action: 'Leave a Proton Drive folder that was shared with you by another user.' It uses a specific verb and resource, and explicitly distinguishes from the sibling tool drive_share_revoke, making the 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?

The description provides explicit when-to-use guidance (for folders shared with you) and when-not-to-use guidance (do not use on folders you own; use drive_share_revoke instead). It also names the alternative tool, giving clear context for selecting this tool over others.

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 the full scope of destruction (all members plus pending invitations, Proton and non-Proton) and the requirement for authentication and confirmed=true. This adds meaningful context about the blast radius and safety mechanism.

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 concise sentences, front-loaded with the primary action, followed by prerequisites and alternatives. No redundant or filler content.

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

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

For a destructive tool with only two parameters and no output schema, the description fully covers the purpose, prerequisites, alternatives, and confirmation requirement. It is self-contained and aligns well with the available structured metadata.

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 both parameters are well-described in the schema. The description reinforces confirmed=true but does not add new parameter-specific semantics beyond what the schema already provides, so the 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 states the tool removes access for every member and every pending invitation on a shared Proton Drive path. It distinguishes itself from sibling tools by explicitly comparing to drive_share_revoke (single person) and drive_share_status (view access).

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-to-use guidance: use drive_share_status first to show who has access, and use drive_share_revoke instead when removing one specific person, citing it as cheaper and less error-prone. Also notes the confirmed=true requirement.

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 flag destructiveHint=true. The description adds valuable behavioral context: 'Requires authentication', 'The link stops working immediately', and 'direct member access...is not affected.' These details go beyond the annotation and help the agent predict side effects without contradicting the destructive 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?

Three sentences, each earning its place: purpose, behavior/requirements, and usage alternative. Front-loaded with the core action, no filler or repetition. Ideal conciseness for a tool with one parameter.

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

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

The tool is simple (1 param, no output schema), and the description covers all essential aspects: what it does, when not to use it, authentication requirement, immediate effect, and impact on other sharing types. It is fully adequate 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 coverage for the single 'path' parameter is 100%, and the schema description is already clear ('Absolute remote Drive path whose public link should be removed (must start with '/')'). The plain-language description adds no further parameter details, but none are needed given the complete 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 opens with a specific verb and resource: 'Remove the public share link from a Proton Drive file or folder.' It clearly differentiates from sibling tools by explicitly stating what it is not for and naming the alternative (drive_share_revoke). This leaves no ambiguity about the tool's function.

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-not-to-use guidance: 'Do not use to remove a specific person's access — use drive_share_revoke instead.' It also clarifies that direct member access (from drive_share_invite) is unaffected, helping the agent understand the tool's scope versus related sharing 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?

Description adds that revoked user receives no notification and requires authentication, complementing destructiveHint=true annotation.

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

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

Four focused sentences with no redundant information, front-loading the core 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?

Covers all necessary context: authentication, notification, pre-condition (drive_share_status), and batch revocation, 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 coverage is 100%, but description adds important context like path must match invitation and email must be confirmed via drive_share_status.

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?

Clearly states 'Remove a specific person's access' and distinguishes from siblings by referencing drive_share_status and advising against role modification.

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

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

Explicitly instructs to call drive_share_status first, explains how to revoke all members, and warns not to use for role changes.

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 far beyond the sparse annotations (openWorldHint, destructiveHint, idempotentHint). It discloses that the link is accessible to anyone without an invitation, that repeated calls update rather than duplicate, that the return shape is variable, and that passwords may appear in shell history—critical behavioral traits 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?

Six sentences, each carrying essential information: purpose, auth, public access, update semantics, return shape, security warning, and alternative tool. No filler or redundancy; the main purpose is front-loaded and every sentence earns its place.

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

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

For a tool with no output schema and moderate complexity, this description is highly complete. It covers public-access implications, update behavior, return-value variability, a security risk, and the relevant alternative, giving the agent enough context 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 coverage is 100%, so the baseline is 3. The description adds context by mentioning that role/password/expiration are updatable on subsequent calls, but it does not add new syntax or format details beyond what the schema already provides for each parameter.

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

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

The description states the core function clearly: 'Create or update a public share link for a Proton Drive file or folder.' The verb phrase is specific and the resource is unambiguous, distinguishing it from sibling tools like drive_share_invite (private sharing) and drive_share_remove_url (removing links).

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 explicit usage guidance: 'Do not use for private sharing with specific people — use drive_share_invite instead.' It also notes that authentication is required and clarifies that the link is publicly accessible without a Proton account, making the when-to-use context very clear.

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 provide readOnlyHint and idempotentHint, and the description adds meaningful behavioral nuance: it returns both accepted members and pending invitations, pending invites may target non-Proton addresses, revoke cancels pending invites, and authentication is required. This goes well beyond the annotation hints.

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?

Every sentence earns its place: purpose, return shape, the important pending-invitation nuance, when to call, and read-only caution. The most important information is front-loaded, and the longer explanatory content is not redundant.

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

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

With no output schema, the description compensates by explicitly describing the return object shape and field semantics. It also covers authentication, use-before-invite/revoke, and read-only behavior, so an agent has everything needed to invoke it correctly.

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

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

The schema already documents the single path parameter in full, including format ('must start with /'), examples, and that it must be an existing file or folder. The description adds little parameter-specific detail beyond saying 'Proton Drive path,' so 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 states a specific verb and resource: 'Return the current sharing state of a Proton Drive path.' It also explicitly distinguishes itself from modifying operations by saying 'Do not call this to modify sharing — it is read-only,' and is clearly differentiated from invite/revoke 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: 'Always call this before drive_share_invite' and 'before drive_share_revoke,' and tells the agent to check the status field to distinguish accepted vs pending members. It also states when not to use it, making the routing unambiguous.

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?

Discloses immediate removal from original path, non-permanent deletion, recoverability, and authentication requirement, adding value beyond the destructiveHint annotation.

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?

Concise with 4 sentences, front-loaded with the main action, and well-structured without unnecessary 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 a single parameter, no output schema, and annotations, the description covers all necessary context: behavior, prerequisites, and alternatives.

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 does not add extra parameter information beyond the schema's own description.

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 action ('move a file or folder to the Proton Drive trash') and distinguishes it from siblings like drive_delete and drive_restore, making the 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 states when to use this tool over drive_delete and when not to use it, including clear alternatives and recovery options.

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 include openWorldHint, so the description carries the full behavioral burden and succeeds. It discloses recursive folder upload, directory structure preservation, return counts, failure semantics (fails if failed > 0), common failure causes, default conflict strategies, and authentication requirements.

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?

Every sentence earns its place: core action, key behavior, return contract, failure modes, defaults, exclusions, and prerequisite steps. The description is dense but efficiently structured and front-loaded with the essential 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 complex tool with no output schema, the description fully explains return values, error conditions, conflict handling, prerequisites, and alternatives. An agent has enough information to call it correctly and handle failures.

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 value above the schema by explaining that conflict strategies are configured separately, defaults to 'skip', and the overall effect on upload results. It does not need to restate the schema's parameter details.

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

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

States a specific verb ('Upload') and resource ('local file or folder to Proton Drive') and even specifies end-to-end encryption. It clearly distinguishes from sibling tools like drive_move and drive_write_file by naming exactly what this tool does and what it does not do.

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 explicit when-to-use guidance and names alternatives: 'Do not use to move files already on Drive (use drive_move)' and 'use drive_write_file'. It also gives a prerequisite workflow: check destination exists with drive_list, and create with drive_mkdir if needed.

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 provide readOnlyHint and idempotentHint. The description adds value by noting that authentication is not required, which goes beyond the annotations. However, it does not elaborate further on behavioral traits.

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, front-loaded with purpose, and no unnecessary words. Every sentence is informative and 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?

Given no parameters and no output schema, the description provides sufficient information about the return value and usage. Combined with annotations, the tool definition is 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?

No parameters exist (schema coverage 100% with empty properties). The description explains the return format, which adds meaning beyond the schema. Baseline for zero parameters is 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 clearly states the tool returns the installed proton-drive CLI and SDK versions as an object with specific keys {cli: string, sdk: string}. It distinguishes from other tools by specifying it does not require authentication and is not for auth state.

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 states when to use: to confirm the correct binary is in PATH before other operations or diagnose compatibility issues. Also provides a clear exclusion: do not use for auth state, instead use drive_auth_status.

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?

Adds important behavioral context beyond annotations: confirms overwriting with user, creates parent directories locally, and requires desktop app. No contradiction with destructiveHint and openWorldHint.

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?

Concise with no wasted words; front-loaded with purpose, then prerequisites, behavior, and caveats in logical order.

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?

Complete for a 2-param tool without output schema: covers purpose, requirements, side effects, and usage boundaries.

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%, baseline 3. Description adds context for path (mapped to local folder) and content (UTF-8), providing extra meaning over schema 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 verb 'write' and resource 'file' within the Proton Drive sync folder context, and it distinguishes from drive_upload by specifying not to use for binary content or without desktop app.

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 mentions when to use (text content, with app running) and when not to (binary, without app) with the alternative drive_upload, plus prerequisites like authentication and environment variable.

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 include destructiveHint:false, so description carries some burden. It discloses requirements (authentication, path format, pre-existing photo) but does not mention what happens on failure (e.g., album not found, photo already in album) or whether the operation is idempotent. It clarifies a non-obvious behavioral trait (does not upload), but leaves other side effects unspecified.

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 concise, front-loaded sentences. The first sentence states the core purpose; the second sets path constraints; the third clarifies a boundary and points to a helper tool. No redundant filler.

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

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

For a simple two-string-parameter tool with no output schema and minimal annotations, the description covers purpose, usage constraints, and a key behavioral caveat. It lacks explicit error-handling information but is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema already covers both parameters with descriptions and examples (100% coverage), so baseline is 3. The description adds value by clarifying that photoPath must reference an existing library item and that the tool does not upload, plus suggesting photos_list_albums to discover albumPath. This enriches 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?

Clearly states the action (add a photo) with source (library) and destination (album), distinguishing it from sibling tools like photos_remove_from_album or photos_create_album. The verb 'Add' and resource phrasing are specific.

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 explicit usage conditions: requires authentication, path prefixes, photo must already exist (not for upload), and points to photos_list_albums for finding album paths. This effectively tells when to use 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.

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

Annotations only include destructiveHint: false, so the description carries the transparency burden. It discloses authentication requirements, the exact creation path (/albums/<name>), the 'not a path' parameter constraint, and the duplicate-name failure behavior—all beyond the annotation's minimal safety signal.

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, front-loaded with the primary action, and every clause adds value: auth, parameter format, creation location, and failure condition. No filler or 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?

For a simple one-parameter create operation with no output schema, the description covers all essentials: what it does, how to pass the parameter, where it lands, failure mode, and authentication. It's fully complete for 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% with a description for 'name', but the tool description adds valuable nuance: 'Pass the album name (not a path)' and explains the resulting path. This goes beyond the schema's example and non-empty constraint, enriching the parameter's 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 uses a specific verb+resource ('Create a new empty photo album in Proton Photos') and clearly distinguishes from siblings like photos_list_albums and photos_delete_album. It also specifies 'empty' and 'new' to disambiguate from add/remove operations.

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

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

Provides clear context: requires authentication, expects a name not a path, and fails on duplicates. It doesn't explicitly name alternatives, but the context makes it obvious this is the creation tool among the sibling list. Slightly short of explicit when-not guidance.

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 crucial behaviors: default refusal for albums containing photos, force override, default photo removal from album with timeline retention, and the save preservation option. This is rich context that substantially exceeds the annotation.

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. Each sentence addresses a distinct aspect (function, auth/confirmation, force, save, path constraint, user confirmation step). No fluff or repetition; structure is logical and front-loaded with the primary 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 destructive tool with no output schema, the description is remarkably complete: it covers prerequisites, safety guards, behavioral nuances, parameter constraints, and a pre-call user confirmation step. It fully prepares an agent to invoke the tool correctly.

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

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

The schema already provides 100% coverage of parameter descriptions, but the description adds meaningful context: 'albumPath must start with /albums/' and clarifies force/save default behaviors (e.g., save=true overrides default removal). This adds value 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 'Delete a Proton Photos album,' a specific verb+resource that clearly states the tool's function. It distinguishes itself from siblings like photos_add_to_album and photos_remove_from_album by targeting album deletion, not photo manipulation.

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 conditions: requires authentication and confirmed=true, force=true to override default refusal for non-empty albums, and save=true to preserve photos. It also instructs to show the user album name and photo count from photos_list_albums before calling, and specifies albumPath format, offering clear when-to-use and prerequisites.

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 carry only openWorldHint, so the description bears the behavioral burden and does well: it discloses the authentication requirement, the filename-collision consequence ('only one copy survives locally' with 'remove'/'skip'), and the all-or-nothing failure mode ('Fails if any item fails to download'). This meaningfully supplements the thin annotation set 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?

Four dense sentences with zero filler, and the purpose is front-loaded in the first sentence. Each subsequent sentence earns its place: auth requirement, collision warning, atomic failure behavior, and sibling routing. Efficient and well-ordered.

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 no output schema and only openWorldHint as an annotation, the description covers the critical decisions: source scope, destination, auth, conflict resolution, failure semantics, and tool routing. The only minor gap is the unspecified success return value, which is of low importance for a download operation whose observable outcome (files in a folder) is self-evident.

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 value beyond the schema by explaining why conflictStrategy matters: multiple timeline photos can share the same filename, and the survival consequence ties the enum options to real outcomes. This is semantic context the schema's per-parameter descriptions do not provide.

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

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

States a specific verb+resource+destination ('Download one or more photos from Proton Photos... to a local folder') and scopes the source explicitly (timeline, album, shared-with-me). The final sentence names the sibling it is not (drive_download), making the boundary unambiguous against the photos_upload and drive_download siblings.

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

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

Explicitly states when not to use it ('Do not use for regular Drive files') and names the alternative ('use drive_download instead'). The source scoping (timeline, album, shared-with-me) further clarifies the intended context. No routing decision is left to inference.

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 and idempotentHint, and the description adds valuable context beyond that: authentication requirement, return format as [{nodeUid}], and a critical path constraint. It also warns that nodeUid is not suitable for add/remove operations, which is behavioral information not present in annotations or schema.

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

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

The description is three concise sentences, front-loaded with the core action. Every sentence adds value: the first explains what it does, the second covers auth and return value, and the third provides an important constraint. No filler or 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?

For a simple read-only list tool with one parameter and no output schema, the description is complete. It explains the return value format, the required path prefix, authentication, and a relevant warning about using Drive paths for mutations. The annotations and sibling context round out the picture, so there are no significant 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?

Schema coverage is 100% for the single parameter albumPath, and the schema already includes the description 'Must start with /albums/' and an example. The tool description repeats this constraint but does not add meaningful new parameter semantics beyond the schema, 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 states the tool's function: 'List the photos in a Proton Photos album.' It specifies the resource (photos in an album) and distinguishes this from sibling tools like photos_list_albums (which lists albums, not their contents). The return format is also mentioned, further clarifying the purpose.

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

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

The description provides clear context: requires authentication, albumPath must start with /albums/, and returns nodeUids. It also gives guidance about related operations ('To add or remove photos, use their Drive path under /photos/'), which implicitly tells the agent when not to use this tool for mutations. However, it does not explicitly state when to use this tool over alternatives, 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 indicate readOnly and idempotent. The description adds valuable behavioral context: requires authentication, return structure [{name, photoCount, isShared, creationTime?}], and path convention /albums/<name>. This goes beyond the annotations and helps the agent understand side-effects and output expectations.

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 main purpose, and every sentence provides essential information (purpose, return format, path convention, exclusions). 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 simple zero-parameter read-only tool, the description fully covers the purpose, output format, prerequisites (auth), and integration with other album tools. It also prevents misuse by contrasting with drive_list. No 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?

With zero parameters, the schema coverage is trivially 100%. The description adds meaning by explaining the return shape and path usage, which is useful even though there are no parameters to document. Baseline for 0 params is 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 clearly states 'List all photo albums in Proton Photos' with a specific verb and resource. It distinguishes from siblings by specifying 'all photo albums' and later contrasting with regular Drive folders, making it unique among the tool list.

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 explicit usage guidance: use the name from this list to build paths for other album tools, and explicitly warns against using it for Drive folders, directing to drive_list instead. This is a clear when-to-use vs alternative.

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 and idempotentHint, providing safety and idempotency. The description adds value by disclosing the default return format ('Returns [{nodeUid}] by default'), the optional behavior with loadDetails ('pass loadDetails=true for full node metadata'), and performance implications ('slower; buffers the whole list in memory first'). This goes beyond what annotations 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 three sentences long, front-loaded with the core purpose, then provides auth requirement, return format, parameter behavior, and alternatives. Every sentence adds necessary information with no redundancy. It is concise yet comprehensive.

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 simplicity (one optional parameter), strong annotations, and absence of an output schema, the description adequately covers the essentials: what it lists, what it returns by default, what happens with loadDetails, authentication, and related tools. No critical information appears missing for an agent to select and invoke this tool correctly.

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

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

The input schema already documents loadDetails with its meaning and default. The description adds extra context by explaining the performance and memory trade-offs ('slower; buffers the whole list in memory first') and reiterates the default return format. This enhances the schema description, so a score above baseline is warranted.

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

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

The description clearly states the tool's function: 'List photos in your Proton Photos timeline' with the explicit caveat '(your full photo library, not scoped to an album)' which distinguishes it from album-scoped siblings like photos_list_album_photos. The verb 'List' and resource 'photos in your Proton Photos timeline' are specific and 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 description provides explicit guidance on when to use this tool versus alternatives: 'Use photos_download to download items by path, or photos_add_to_album to add them to an album.' It also clarifies the scope ('not scoped to an album'), implying when to choose this over album-specific listing tools. This is clear and directly addresses 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?

The description adds important context beyond the destructiveHint annotation by clarifying that the destructive scope is limited to album membership, not library deletion. It also discloses the authentication requirement, which is valuable behavioral info.

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, each adding value: purpose, authentication, and path constraints with behavioral effect. No redundant words.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, behavioral impact, prerequisites, and path constraints. It is complete enough for an agent to confidently select and invoke 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?

The input schema already provides full parameter descriptions, including path format constraints and examples. The tool description reinforces the path prefix requirements but does not add new semantic information beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Remove a photo from a Proton Photos album' and clearly clarifies the scope by saying 'without deleting it from your library.' This differentiates it from sibling tools like photos_add_to_album and photos_delete_album.

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 (removing from an album while keeping the photo) and mentions the authentication requirement. However, it does not explicitly name alternative tools or state when not to use it, though the context implies 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?

The description adds that authentication is required and clarifies that it's a partial update allowing either field, beyond the destructiveHint=false annotation. It does not contradict any annotations, and the annotation is minimal, so the description adds meaningful 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?

Three sentences with no fluff. The purpose, constraints, and a usage hint are packed efficiently, front-loading the tool's primary function.

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 low complexity and full schema coverage, the description covers the purpose, required parameters, authentication, and how to obtain the cover photo. It lacks an explicit mention of return value, but that's not critical for an update 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?

The input schema already provides 100% coverage with clear descriptions for name, albumPath, and coverPhotoUid. The description adds no extra semantic detail beyond referring to these fields, 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 states the tool renames an album or changes its cover photo, using specific verbs and a resource. It distinguishes from sibling tools like photos_create_album and photos_delete_album by specifying the exact mutation types.

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

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

It explicitly notes the authentication requirement and the constraint that at least one of name or coverPhotoUid must be provided. It also directs users to photos_list_album_photos to discover nodeUid values, giving practical usage context, though it doesn't mention 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?

With only openWorldHint in annotations, the description carries the behavioral burden and does so thoroughly. It discloses that non-photo/video files are silently skipped, folders are flattened, files are never overwritten, and duplicates are handled only via rename or skip.

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. Each sentence adds distinct value: purpose, authentication, filtering, folder behavior, conflict resolution, and an explicit alternative. No wasted words or repetition of schema details.

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 two-parameter upload tool with no output schema, the description covers all essential operational context: file types, folder flattening, overwrite avoidance, duplicate handling, authentication, and the correct sibling alternative. Nothing critical needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: it clarifies localPaths refers to local photo/video files or folders, explains folder recursion and flattening, and defines the duplicate-matching logic as name + content hash for the conflictStrategy parameter.

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

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

Description opens with a specific verb and resource: 'Upload one or more local photo or video files directly into your Proton Photos library.' It also explicitly distinguishes itself from drive_upload by saying not to use it for regular Drive files, so sibling confusion is avoided.

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 explicit routing guidance: 'Do not use for regular Drive files — use drive_upload instead.' Also states authentication requirements, file-type filtering, folder behavior, and duplicate resolution so an agent knows exactly when and how to invoke this tool.

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