Proton Drive MCP

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

The annotations already declare idempotentHint=true and destructiveHint=true. The description reinforces and expands on these by explicitly stating the destructive consequence ('all file and sharing operations will fail until the user runs auth login again') and the idempotent nature ('Idempotent: safe to call even if already logged out'). It also discloses the requirement for user confirmation before invocation, which is a critical behavioral trait not captured by annotations alone. There is no contradiction with annotations.

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

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

The description is concise, with every sentence adding critical information. It front-loads the core action ('Clear the stored session') followed by consequences, usage context, a cautionary note, and the prerequisite. There is no wasted or redundant language, and the structure flows logically from what the tool does, to when to use it, to how to invoke it safely.

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 that there is no output schema, the description adequately covers what happens after invocation (operations fail until re-login) and the safety caveat. It also addresses the key contextual aspects: user confirmation, idempotency, and the impact on subsequent operations. For a tool with a single boolean parameter and destructive action, this is comprehensive and leaves no gaps for an agent to fill.

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

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

The input schema describes the 'confirmed' parameter fully with the requirement that it must be true and only set after user approval. The description adds value by explicitly tying this parameter to the workflow ('Requires confirmed=true') and explaining why it's necessary. While the schema covers 100% of the parameter semantics, the description reinforces the mandatory nature and user-interaction precondition, which justifies a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: clearing the stored Proton Drive session from the OS keychain. It uses a specific verb ('Clear') and resource ('session'), which distinguishes it from other drive_* tools. It also explicitly mentions the consequence of logout (all file and sharing operations fail) and provides an idempotency hint, ensuring an agent knows exactly what this tool does.

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: 'Use on shared machines to prevent session persistence.' It also states when not to use it: 'Do not call during an active workflow — it will break all subsequent drive_* calls.' Furthermore, it specifies a prerequisite: 'Requires confirmed=true — describe the action to the user and get their explicit OK first.' This is comprehensive and leaves no room for misinterpretation.

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?

Annotations already declare destructiveHint=false and idempotentHint=false. The description adds valuable behavioral context beyond annotations: the original is preserved, destinationPath is a parent folder rather than a full path, authentication is required, and copying large folder trees has storage-cost implications. It does not mention overwrite or failure behavior if the destination exists, but the added context is substantial.

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 action and uses every sentence for a distinct purpose: action, non-move guarantee, destination semantics, newName condition, sibling alternative, and storage-cost caution. It is slightly longer than strictly necessary because 'Requires authentication' is likely true for all sibling tools, but it remains well-structured and readable.

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

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

For a copy tool with three well-documented parameters, the description covers the main operation, sibling differentiation, parameter nuances, and a practical caveat. It lacks explicit detail on what happens when the destination already exists or whether folder copies are recursive, but those are not critical for basic correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that destinationPath is the target PARENT folder unlike drive_move, and by reinforcing that newName is required for same-folder duplication. This extra sibling distinction raises it above baseline.

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

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

The description opens with a specific verb and resource: 'Copy a file or folder to another location on Proton Drive.' It explicitly differentiates from drive_move by stating 'The original is preserved — this is not a move' and notes the destinationPath semantic difference, so an agent can distinguish sibling tools clearly.

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: 'Use drive_move when you want to relocate without keeping the original.' It also explains when newName is required and warns against duplicating large folder trees without user awareness, providing both alternatives and exclusions.

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?

Beyond the destructiveHint annotation, the description discloses a wealth of behavioral details: localPath is a destination folder, the item is renamed to its remote basename, downloads are recursive, conflict strategies have defaults, the call fails if any file fails, confirmed=true is required for 'remove', and the return value is only counts rather than the actual path. It also notes live verification against CLI v0.8.0, adding confidence. No contradiction with annotations.

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

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

The description is dense but every sentence earns its place. It is front-loaded with purpose, then flows through path semantics, recursion, conflict strategies, return behavior, failure semantics, and exclusions. The length is justified by the tool's complexity and the absence of an output schema.

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

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

For a download tool with 5 parameters, no output schema, and destructive conflict strategies, this description is remarkably complete. It covers prerequisites, side effects, path construction, return values, failure behavior, and alternative tools. An agent has enough context to invoke it correctly and set user expectations.

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

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

Although schema coverage is 100%, the description adds meaning well beyond the schema: it explains that localPath is a destination folder rather than a file path, provides a concrete example of resulting paths, clarifies default conflict strategies, and specifies when confirmed is mandatory. This materially improves an agent's ability to set parameters correctly.

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

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

The description opens with a specific verb and resource: 'Download a file or folder from Proton Drive to the local filesystem.' It also explicitly differentiates from siblings by naming drive_move and drive_read_file as alternatives for other intents, so an agent can tell exactly what this tool is for.

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

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

The description gives explicit usage boundaries: 'Do not use to move files within Drive (use drive_move) or to read a small text file's contents (use drive_read_file...).' It also explains when confirmed=true is required, which is critical for the destructive conflict strategies. This is strong when-to-use vs alternative 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 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, so the safety profile is covered. The description adds real value on top: the authentication requirement and the output-shape behavior (verification wrappers unwrapped, duplicate/noise fields dropped, verbose=true yields the raw CLI node whose exact shape is not guaranteed). This gives the agent expectations for what a successful call returns.

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?

Five sentences, each earning its place: purpose, auth, return behavior, when-to-use, and exclusion. Slightly dense but properly front-loaded with the purpose and scoping before the alternative routing.

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 metadata-read tool with only 2 well-documented params and read-only/idempotent annotations. The description covers purpose, authentication, return shape behavior, and usage boundaries. The exact fields of the trimmed node are not enumerated, but that is acceptable since the raw shape is explicitly 'not guaranteed' anyway.

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

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

Schema description coverage is 100%, so the schema already documents both parameters clearly. The description reinforces the verbose behavior (raw CLI node vs trimmed) but adds little meaning beyond what the schema states. Baseline 3 is appropriate when the schema carries the burden.

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

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

States a specific verb and resource: 'Get full metadata for a single Proton Drive file or folder, including latest revision details.' It also distinguishes itself from the sibling drive_list by naming it directly, so an agent can tell the two apart without opening their schemas.

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

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

Explicitly gives the trigger condition ('Use when you need details drive_list doesn't return (e.g. revision info) for one specific known path') and names the alternative plus an exclusion ('Do not use to enumerate a folder's children — use drive_list instead'). Nothing 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 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 discloses that the decline is permanent, that the sender is not notified, and that user confirmation is required before proceeding. These are exactly the behavioral details an agent needs for a destructive action.

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 tight, front-loads purpose, and packs in prerequisites, permanence, and confirmation requirements. Minor redundancy exists between 'Get the invitation uid... first' and 'Do not guess the uid — always fetch it,' but this is a deliberate emphasis rather than wasted space.

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 simple two-parameter schemaam, a destructiveHint annotation, and no output schema, the description covers everything needed to call the tool correctly: source of uid, required confirmation, permanence, sender notification behavior, and authentication prerequisite.

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 uid's source and confirmed's true requirement at 100% coverage, so the description adds little new parameter-level meaning. It reinforces 'always fetch the uid' and 'get explicit OK,' but these largely restate the schema.

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

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

The description opens with a specific verb and resource: 'Reject a pending Proton Drive sharing invitation.' This unambiguously identifies the operation and distinguishes it from 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?

Clear context is given: the tool is for rejecting pending invitations, the uid must come from drive_list_invitations first, and confirmed=true is required before use. It stops short of explicitly naming alternatives such as drive_invitation_accept, but the workflow is 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?

Annotations already mark the tool as readOnly and idempotent, and the description adds extensive behavioral context: requires authentication, returns a paginated object with a specific shape, defaults to limit 200, lists root when path is '/', and is not recursive. This goes well beyond the structured annotations.

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

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

The description is information-dense but well organized: purpose, return shape, root behavior, non-recursive caveat, usage context, and sibling exclusion. Every sentence carries useful information and none are 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?

Even though there is no output schema, the description fully defines the response shape, item fields, pagination fields, defaults, and special root behavior. Combined with the fully documented input schema and readOnly annotations, the agent has everything needed to invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already fully documents path, limit, and offset with descriptions and constraints. The description adds a small amount of path-related context (listing '/' returns roots and that limit defaults to 200), but does not meaningfully deepen 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?

States a specific verb ('List') with a clear resource ('immediate children of a Proton Drive folder') and explicit non-recursive scope. The description also distinguishes this from drive_list_trash by name and behavior, so an agent can identify it among 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?

Provides explicit when-to-use guidance: use before drive_upload to confirm the destination and before drive_download to verify the remote path. It also explicitly says do not use for trash and names the alternative drive_list_trash, leaving no ambiguity about routing.

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 declare readOnlyHint and idempotentHint, so the safe-read behavior is covered. The description adds valuable context: authentication requirement, exact return shape, pagination defaults, ordering, optional fields, and the critical non-unique-names caveat with uid guidance.

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

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

The description is dense but every sentence earns its place: purpose, return shape, uniqueness caveat, use cases, and exclusion of active-file listing. The most important scoping 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 read-only list tool with no output schema, the description fully compensates by specifying the return structure, pagination fields, item fields, ordering, and duplicate-name behavior. An agent has enough information to invoke it 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 description coverage is 100%, so limit and offset are already fully documented. The description restates the default limit of 100 and provides pagination context, but does not add new parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('List all files and folders currently in the Proton Drive trash') and explicitly contrasts with drive_list for active files. This fully distinguishes it from sibling tools.

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

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

It gives explicit when-to-use guidance: before drive_restore to find a trashed item's exact path, and before drive_empty_trash to show the user what will be deleted. It also tells the agent not to use it for active files and to use drive_list instead.

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 annotations (readOnlyHint, idempotentHint), the description discloses critical runtime prerequisites (env var, app running, local sync), the 1 MB text-file limit, and the error behavior for binary/large files. It also names the fallback tool. This is rich behavioral context that the agent needs to call it correctly, and it does not contradict the annotations.

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

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

The description is front-loaded with the core purpose and follows with prerequisites, limitations, and an alternative. It is logically structured but slightly redundant—'returns an error for binary files or larger files (use drive_download instead)' and the final sentence repeat the same exclusion. Still, it remains concise and scannable.

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 single-parameter read tool, the description covers prerequisites, limits, and alternatives thoroughly. It does not explicitly state the return format (e.g., raw text content) or encoding, but 'Read the text contents' implies text is returned. Given no output schema, this is a minor gap; the description is otherwise 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 input schema already provides a thorough description of the single parameter 'path' (absolute remote path, must start with '/', mapped to local sync folder). With 100% schema description coverage, the description adds no extra parameter-level meaning beyond what is already documented. Baseline 3 is appropriate.

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

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

The description clearly states the action (read) and resource (file contents from local Proton Drive sync folder). It explicitly differentiates from drive_download by specifying that binary files, files over 1 MB, or unsynced files should use drive_download instead. This makes it easy for an agent to distinguish this tool from its sibling.

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

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

It provides explicit when-to-use conditions: requires PROTON_DRIVE_SYNC_PATH environment variable, the desktop app must be running, and the file must be synced locally. It also gives direct exclusion criteria and a named alternative: 'Do not use for files not yet synced locally, binary files, or files over 1 MB — use drive_download instead.' This leaves no ambiguity about tool selection.

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?

Beyond the openWorldHint annotation, the description discloses immediate email notification, the risk of silent role overwrite, and the authentication requirement. It doesn't detail response format or error cases, but the key behavioral traits are well covered.

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

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

Every sentence is functional: purpose, side-effect warning, role definitions, prerequisite, alternative. It is front-loaded and dense without redundancy. The length is justified by the critical warnings.

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 5-param tool with no output schema, the description covers all essential operational aspects: purpose, side effects, prerequisites, alternatives, and parameter semantics. An agent can safely invoke it correctly after reading this description.

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 by explicitly restating role semantics and emphasizing the confirmed parameter's requirement, which reinforces the schema but goes slightly beyond by explaining the action's side effects. This justifies a 4.

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

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

The description uses a specific verb and resource: 'Invite a person to access a Proton Drive file or folder by email.' It clearly differentiates from siblings like drive_share_revoke and drive_share_status by stating its core function and side effect. The scope is unambiguous.

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

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

Explicitly states prerequisites: 'Do not call without first running drive_share_status' and warns about duplicate invitations overwriting roles. It also points to the alternative for removal: 'To remove access, use drive_share_revoke.' The confirmed=true requirement is explicitly tied to user approval.

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 declare destructiveHint=true, and the description builds on that by defining the exact blast radius: 'Removes your access to the shared folder — the owner and other members are not affected.' This scoping of the destructive effect goes beyond the annotation, as does the confirmed=true safety gate and the authentication requirement. A minor gap: it doesn't state what the response looks like, but for a mutation tool with output-less behavior that is acceptable.

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?

Front-loaded with the core action, and each subsequent sentence earns its place: it scopes who is affected, routes to the correct alternative, and states the confirmation precondition. Slightly longer than strictly necessary, but every clause adds distinct operational information rather than padding.

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

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

For a destructive tool with only two simple parameters, the description covers the essential decision points: when to use, when not to use, who is affected, and the required confirmation gate. With no output schema and a destructiveHint annotation present, it is nearly complete; the only minor omission is clarifying the result/success indication, which is a low-stakes gap.

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

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

Schema coverage is 100%, so both parameters are already fully documented in the schema, which sets the baseline at 3. The description does add emphasis on the confirmed parameter ('Must be true. Only set after the user explicitly approved') beyond the schema's wording, which is a small value-add but not enough to push past the baseline given how thorough the schema already is.

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 ('Leave') and resource ('a Proton Drive folder that was shared with you'), and immediately distinguishes itself from the sibling drive_share_revoke by naming the exact difference: leaving vs. revoking. An agent can tell them apart without opening either schema.

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

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

Explicit when-to-use ('shared with you by another user'), and explicit when-not-to-use with the named alternative ('Do not use on folders you own — use drive_share_revoke'). It also adds a hard precondition: 'Requires confirmed=true — describe the action to the user and get their explicit OK first.' Nothing 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?

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 only declare destructiveHint=true, but the description adds substantial behavioral detail beyond that: 'The link stops working immediately — direct member access (from drive_share_invite) is not affected.' It also discloses the authentication requirement and the confirmation prerequisite. This gives the agent a complete safety picture without contradicting 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?

Three concise sentences deliver all critical information. The first sentence states the action, the second explains effects and non-effects, the third provides usage exclusion and confirmation guidance. No redundant wording; every sentence adds value, and the most important details are 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 destructive action, the description covers all necessary operational aspects: what it does, when to avoid it, side effects, prerequisites (authentication, confirmation), and direct impact. No output schema exists, so return-value details are not expected. An agent can correctly call this tool after reading the description alone.

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 documented, so the baseline is 3. The description adds extra meaning for the 'confirmed' parameter by explaining its purpose in operational terms ('Requires confirmed=true — describe the action to the user and get their explicit OK first'), which is more actionable than the schema's 'Must be true' line. It also implicitly clarifies that 'path' is the target of removal, though no additional syntactic detail is given.

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 precise action and target: 'Remove the public share link from a Proton Drive file or folder.' It clearly identifies the resource and distinct operation, and explicitly differentiates from the sibling drive_share_revoke by stating 'Do not use to remove a specific person's access — use drive_share_revoke instead.' This prevents agent confusion between similar share management 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?

Provides explicit when-to-use context: it is for removing a public share link, and it gives an explicit exclusion with a named alternative: 'Do not use to remove a specific person's access — use drive_share_revoke instead.' It also states the mandatory confirmation step ('Requires confirmed=true — describe the action to the user and get their explicit OK first'), which tells the agent how to use the tool safely.

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: true, so the description carries the full burden of behavioral disclosure. It adds crucial context: 'Requires authentication,' 'The revoked user receives no notification,' 'Fails if the address is not a current member or pending invitee (matched case-insensitively),' and the mandatory confirmed=true gate. These go beyond the annotation and prepare the agent for side effects and failure modes.

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 delivers distinct value: purpose, authentication, no-notification, pre-check requirement, failure condition, alternative tool, role-modification caveat, and confirmation gate. The most critical constraint (confirmation) is saved for the end, but the front is not padded. No redundancy; well structured for an agent to parse.

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

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

For a destructive action with only destructiveHint annotation and no output schema, the description covers all needed context: prerequisites, failure conditions, exact-match requirements, confirmation flow, and alternatives. An agent can safely execute this tool without additional lookup.

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

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

Schema coverage is 100%, so the schema documents each parameter. The description adds meaning beyond that: for email it mandates matching the exact address from drive_share_status, for path it requires matching the original invitation path, and for confirmed it explains the user-approval prerequisite. This is more than a baseline; it actively guides correct parameter values.

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: 'Remove a specific person's access to a Proton Drive file or folder.' It specifies the resource (file/folder) and scope (specific person), distinguishing it from drive_share_remove_all (remove everyone) and drive_share_status (check). The verb and object are 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 and when-not-to-use guidance: 'Always call drive_share_status first to confirm the email and current role before revoking,' 'Do not use to modify a role — revoke and re-invite with the new role instead,' and 'To remove everyone at once use drive_share_remove_all.' It also clarifies the confirmation requirement ('Requires confirmed=true — describe the action to the user and get their explicit OK first'). No other tool definition offers this level of conditional routing.

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 and idempotentHint annotations, the description adds critical behavior: replaces existing link settings, omitting password/expiration removes them and yields a warning, expiration limited to ~90 days, and the password will appear in shell history/process list. It also discloses the response shape and that fields may be absent, providing transparency not required 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?

The description is detailed but organized: purpose first, then conditions, response, security note, and alternatives. Each sentence carries functional weight, with no filler. It is longer than typical but justifiably so given the tool's complexity and destructive nature.

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 5 parameters, no output schema, and destructive behavior, the description covers all essential aspects: authentication, return shape, destructive semantics, security implications, and the confirmed parameter. It also distinguishes from siblings and sets usage expectations, leaving no critical gaps for an agent to call 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?

Schema already has high coverage (100%) with detailed parameter descriptions, so baseline is 3. The description adds valuable semantics: the 90-day expiration limit, the replace-remove behavior tied to password/expiration, and the security note about the password appearing in shell history. This goes beyond the schema's per-parameter text, though not maximally exhaustive.

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 action ('Create or update a public share link') with a clear resource ('Proton Drive file or folder'), and explicitly contrasts it with drive_share_invite for private sharing. It also notes that anyone with the link can access the item without an account, 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-not-to-use guidance by directing to drive_share_invite for private sharing with specific people. Also specifies the prerequisite that confirmed=true must be set after user approval, and explains the updating behavior (calling again replaces settings). This fully covers when and how to use the tool.

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

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

Annotations already 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?

Beyond the destructiveHint annotation, the description discloses several behavioral traits: 'Requires authentication', 'For folders, uploads recursively and preserves directory structure', 'fails the call if failed > 0 (common causes: quota exceeded, destination path not found, permission denied)', and the destructive 'replace' behavior that 'trashes the existing remote item' tied to the confirmed flag. This is substantial context that aids safe and effective invocation.

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

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

The description is dense yet efficient, front-loading the primary purpose in the first sentence and then adding critical operational details in a logical order: authentication, recursion, return behavior, conflict defaults, exclusions, prerequisites, and the destructive replace confirmation. Every sentence contributes new information without 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 there is no output schema, the description properly explains the return structure 'Returns {uploaded, skipped, failed} counts' and failure conditions. It covers authentication, recursion, conflict strategies, exclusions, prerequisite folder checks, and the destructive nuance of 'replace'. For a tool with 5 parameters and 2 enums, this level of detail is sufficient for correct use without further external knowledge.

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 meaningful cross-parameter semantics beyond the schema: it notes that conflict strategies 'are set separately for files and folders' and 'both default to skip', and that 'confirmed=true' is specifically required when either conflict strategy is 'replace'. This clarifies conditional requirements and defaults not fully expressed 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 opens with 'Upload a local file or folder to Proton Drive with end-to-end encryption', clearly stating the verb, resource, and distinguishing feature. It further differentiates from siblings by explicitly naming drive_move and drive_write_file as alternatives for different scenarios, leaving no ambiguity about the tool's core 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 provides explicit when-not guidance: 'Do not use to move files already on Drive (use drive_move) or to write text content directly (use drive_write_file if PROTON_DRIVE_SYNC_PATH is set)'. It also gives a prerequisite workflow: 'Ensure destination folder exists first with drive_list; create it with drive_mkdir if needed', and notes the conditions under which the call fails, helping agents decide when this tool is appropriate.

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?

Even though destructiveHint=true and openWorldHint=true are already in annotations, the description adds substantial context: it only touches the local sync folder, creates parent directories, refuses overwrite without confirmed=true, and enforces a 5 MB content limit. No contradiction exists between the description and annotations.

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

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

The description is well-structured and front-loaded with the core action, but it is somewhat verbose. The final sentence 'Also requires confirmed=true when the file already exists (it would be overwritten)' repeats the earlier overwrite-and-confirmation statement, which reduces conciseness.

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 mutating file-write tool, the description is highly complete: it covers environmental prerequisites, side effects (parent dir creation, overwrite behavior), content constraints, and the correct alternative tool. Given there is no output schema, the absence of return-value detail is not a significant gap for deciding whether and how to invoke this tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds value beyond the schema by explaining the 5 MB content limit, the mapping of the 'path' parameter to the local sync folder, and the user-approval meaning of 'confirmed'. It does not merely repeat parameter names or types.

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: 'Write text content to a file in the local Proton Drive sync folder.' It also differentiates from drive_upload by explicitly stating it is not for binary content or uploads requiring the desktop app to be absent. This makes the tool's purpose unambiguous among many sibling 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?

The description gives explicit when-to-use and when-not-to-use guidance: use for local text writes with the desktop app running, avoid for binary content and use drive_upload instead. It also states prerequisites like the PROTON_DRIVE_SYNC_PATH environment variable and the desktop app requirement, leaving little 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 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?

destructiveHint=true only marks the operation as destructive; the description goes well beyond by requiring confirmed=true, explaining the default refusal to delete non-empty albums, documenting force behavior, and clarifying that deleting an album does not remove photos from the timeline. It also honestly warns that save's exact effect is undocumented upstream.

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, covering safety, parameter semantics, path constraints, and pre-call user communication. There is no filler or restatement of the schema, and the most important destructive behavior appears early.

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 album deletion with no output schema, the description covers authentication, confirmation, force behavior, path requirements, the fact that photos survive in the timeline, and the required pre-call confirmation step. Nothing essential for correct invocation is missing.

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

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

Though schema coverage is 100%, the description adds real meaning: force's override behavior, save's ambiguous upstream effect with a default-off recommendation, confirmed as a mandatory user acknowledgement, and albumPath's required /albums/ prefix. This significantly exceeds what the schema alone communicates.

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

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

Opens with 'Delete a Proton Photos album' — a specific verb and resource. The added detail about refusing to delete albums with photos and the independence of photos from albums makes clear this removes the album container, not the underlying photos, distinguishing it from photos_remove_from_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?

Provides clear operational guidance: force should only be passed to override the default protection, save should be left off unless explicitly requested, albumPath must start with /albums/, and the user must see album name and photo count before calling. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops short of a 5.

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

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

Annotations only supply openWorldHint and destructiveHint flags; the description enriches them with precise semantics: the destructive scope is 'deletes the existing LOCAL file' and only under conflictStrategy 'remove' (which requires confirmed=true), the filename-collision survival behavior for 'skip' vs 'rename', the authentication requirement, and the fail-fast 'Fails if any item fails to download' behavior. None of this contradicts the annotations.

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

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

The main purpose is front-loaded in the first sentence; the remaining short sentences each carry distinct information: authentication, collision behavior, failure semantics, sibling routing, and the confirmation requirement. There is no filler or tautology.

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, multi-strategy tool with four parameters, the description covers purpose, source scopes, authentication, edge-case behavior, failure semantics, the alternative tool, and the confirmation safety latch. The only gap is the success return/result format, which is unstated and uncompensated by any output schema — though the side effect (files placed in localFolder) makes this a minor omission.

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 earns a point above baseline by explaining cross-parameter consequences rather than re-listing definitions: why multiple timeline photos sharing a filename makes conflictStrategy critical (only one copy survives with 'remove'/'skip'), and the conditional coupling of confirmed=true to 'remove'. This reasoning is not present in the individual parameter 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 opens with a specific verb and resource: 'Download one or more photos from Proton Photos (timeline, an album, or shared-with-me) to a local folder.' It enumerates the source scopes and destination, and distinguishes itself from the sibling drive_download by explicitly scoping to photos rather than regular Drive 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?

Gives an explicit exclusion with a named alternative: 'Do not use for regular Drive files — use drive_download instead.' It also defines the tool's domain (timeline, album, shared-with-me) so an agent can select it over the many Drive-oriented siblings.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds substantial behavioral detail: it returns a paginated structure with {items, total, offset, limit, hasMore}, explains the item shape with and without loadDetails, and warns that nodeUid is not the path to use for mutations. This goes well beyond the annotations.

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

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

The description is three focused sentences: the action, the return shape and defaults, and a critical usage caveat. It is front-loaded with the core purpose and every sentence carries useful information without 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 read-only list operation with four well-documented parameters and no output schema, the description provides the essential return shape, pagination fields, default limit, and authentication requirement. It is sufficiently complete for an agent to call and interpret results 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 all parameters with 100% coverage, so the baseline is 3. The description adds value by clarifying the default limit, the effect of loadDetails on item fields, and the important caveat that nodeUid cannot be used for add/remove operations. This extra context aids correct invocation.

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 lists photos in a Proton Photos album, with a specific verb and resource. It distinguishes itself from sibling tools like photos_list_albums and photos_list_timeline by focusing on album contents and the /albums/ path requirement.

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 pagination defaults are specified. It does not explicitly name alternatives, but the last sentence clarifies when to use Drive paths under /photos/ for add/remove operations, preventing misuse.

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, so the safety profile is covered. The description adds valuable behavioral context: authentication requirement, default limit of 50, newest-first ordering, pagination fields, and the token-cost tradeoff of loadDetails. This goes well beyond the annotations.

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

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

Three well-structured sentences: first states purpose and scope, second summarizes output and behavior, third routes to alternative tools. Every sentence earns its place, and the most important scoping 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?

Given there is no output schema, the description fully compensates by documenting the return shape, pagination fields, item fields, and loadDetails variant. It also covers authentication, defaults, ordering, and relevant sibling tools. Nothing important is missing for an agent to call this 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 schema already documents all three parameters. The description adds extra meaning: default limit 50, newest-first ordering, pagination semantics via offset, and the performance/token implications of loadDetails. This improves on the baseline without being essential.

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 ('List photos') and a clear resource ('your Proton Photos timeline'), and explicitly scopes it to the full photo library rather than an album. This differentiates it from sibling album-scoped tools such as photos_list_albums and photos_list_album_photos.

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

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

It explicitly states what this tool is for and what it is not ('not scoped to an album'), and then routes to the appropriate siblings: photos_download for downloading items and photos_add_to_album for adding to an album. This gives an agent clear selection 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?

Annotations already declare destructiveHint=true. The description adds valuable context: it clarifies that the photo is removed only from the album and stays in the timeline, explicitly stating it is not deleted from the library. It also discloses the requirement for user confirmation (confirmed=true) and path constraints, which are behavioral traits beyond the annotation. No contradiction with annotations.

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

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

The description is three sentences, front-loaded with the core purpose. Each sentence earns its place: purpose, path constraints, and confirmation requirement. No fluff or repetition of obvious 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 destructive tool with 3 parameters and no output schema, the description covers everything an agent needs to call it correctly: the exact action, the confirmation requirement, path constraints, and what it does NOT do (delete from library). It omits error handling, but that is not essential for invocation. The combination of description and annotations 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?

Schema description coverage is 100% — every parameter has a detailed description including path prefixes and the confirmed flag. The tool description repeats these constraints (e.g., 'albumPath must start with /albums/') without adding new meaning. It does add context about the action's scope (stays in timeline), but this is not parameter-specific. Per baseline, with high coverage, a 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 verb and resource: 'Remove a photo from a Proton Photos album without deleting it from your library.' This distinguishes it from siblings like photos_add_to_album (add) and photos_delete_album (delete whole album). It also specifies the scope (album only) and the confirmation requirement, making the purpose unmistakable.

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

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

The description gives clear context: it requires authentication, specific path prefixes, and explicit user confirmation (confirmed=true). It implies when to use it (when removing a photo from an album without deleting it from the library) but does not explicitly name alternative tools or conditions for choosing this over them. This is a minor gap given the specificity.

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.