Proton Drive MCP

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

Annotations already declare destructive and idempotent, but description adds key behavioral details: session is cleared from OS keychain, file/sharing ops fail until login, and confirmed=true is required after explicit user approval. No contradiction.

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

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

Four short sentences, front-loaded with the action and consequence. The standalone 'Idempotent' sentence partly repeats the annotation, a minor redundancy, but overall efficient.

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

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

For a one-parameter auth logout with annotations covering safety traits and no output schema, description provides necessary postcondition and approval requirement. Complete for agent 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%; the confirmed parameter is fully documented in the schema. Description reinforces the approval requirement but adds no format or syntax beyond the schema; baseline 3.

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

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

States a specific verb ('Clear') and resource ('stored Proton Drive session from the OS keychain'), plus the postcondition that all file and sharing operations fail until login. Distinguishable from sibling auth/status tools by name and scope.

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?

Clearly situates use: sign out, requires explicit user approval and confirmed=true; warns operations fail until login. Does not explicitly name alternatives such as drive_auth_status or when not to use, so not 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?

Goes well beyond the readOnlyHint/idempotentHint annotations: it discloses the return shape ({authenticated: boolean}), the implementation workaround (no CLI status command, so it probes /my-files), and a privacy boundary (does not expose the account email). This is exactly the kind of non-obvious behavior an agent needs.

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 compact sentences, front-loaded with the purpose and return value, then the mechanism, then the constraint. Every sentence carries information an agent would otherwise have to guess.

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?

There is no output schema, but the description supplies the return type inline, plus the probe mechanism and session prerequisite. Nothing needed to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate, and it correctly says nothing about inputs.

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 ('Check whether the Proton Drive CLI has an authenticated session') and implicitly distinguishes itself from drive_auth_logout and the rest of the drive_* family. An agent can identify the tool's job without opening the schema.

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

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

The final sentence tells the agent when this matters: all other drive_* tools except drive_version require a valid session, making this the natural pre-flight check. It stops short of explicitly naming when not to use it (e.g. drive_version works unauthenticated), but the context is clear.

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

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

The lone annotation is destructiveHint=false, so the description carries most of the burden and delivers: a dry-run/plan mode, a conditional execute mode that aborts on problems, and the 200-item ceiling. This goes well beyond the annotation by disclosing gating and safe-preview behavior.

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

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

Four tight sentences, front-loaded with the core action and scope before the execution conditions. Every sentence carries a distinct fact (cap, name retention, plan mode, execution gate), with no filler.

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

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

For a mutation tool with only destructiveHint=false and no output schema, the description covers the operational workflow and what the non-confirmed call returns. Minor gaps remain, such as how name collisions are treated and what permissions are required.

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, but the description adds genuine meaning the schema lacks for 'confirmed' by explaining that omitting it produces a dry-run plan rather than an error. That is behavioral semantics beyond the field's own text.

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 ('Move items into one existing folder'), with a concrete batch cap ('up to 200') and a retention rule ('keeping names'). The bulk scope implicitly but clearly distinguishes it from the single-item drive_move 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?

Spells out the two-phase workflow explicitly: omitting confirmed yields a plan and problems only, while confirmed=true executes only when no problems exist. It also states the prerequisite (confirmed=true only after explicit user approval), leaving nothing 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?

Discloses behavior well beyond annotations: the 200-item cap, the dry-run/plan semantics, the gating on problem detection, and the explicit user-approval prerequisite for the write path. The reversibility framing (drive_restore recovers) is also stated, consistent with destructiveHint=false.

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 short, front-loaded sentences that each carry distinct information (scope, recovery path, dry-run behavior, execution gate). No filler or repetition.

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

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

For a two-parameter mutation tool with no output schema, the description covers purpose, prerequisites, and both execution modes adequately. It could say more about the shape of the returned plan/problems, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters (baseline 3). The description adds real meaning beyond it by explaining that confirmed=true asserts execution only after problem-free validation and explicit approval, not merely a boolean flag.

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 ('Trash up to 200 items') with an explicit scope limit, and immediately names the recovery sibling (drive_restore). This distinguishes it from single-item drive_trash and from drive_empty_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 spells out both modes: without confirmed it only produces a plan and problems, with confirmed=true it executes only when no problems exist, and it requires confirmed=true after explicit user approval. The when-to-use and when-not-to-act conditions are fully covered.

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, so the safety profile is covered. The description reinforces that the original stays, but that is largely redundant with destructiveHint=false, and it does not add richer behavioral details such as permission requirements, overwrite/collision behavior, or rate limits.

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: copy action first, behavioral note second, parameter distinctions third. Every sentence adds relevant selection or invocation context with no wasted prose.

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 full schema coverage, existing annotations, and no output schema, the description covers the essential copy semantics and sibling-tool distinction. It is nearly complete, though collision behavior and permission expectations for a non-idempotent copy are not addressed.

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 useful semantic contrast by explaining that destinationPath is a target PARENT folder unlike drive_move, and reinforces that newName is required when duplicating inside the same folder.

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 ('Copy a file or folder on Proton Drive'), clarifies the non-mutating effect ('the original stays'), and explicitly distinguishes drive_copy from drive_move. An agent can identify the correct operation without opening sibling 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?

Provides clear usage context: destinationPath is a parent folder, unlike drive_move, and newName is required to duplicate an item inside its own folder. It does not enumerate when-not-to-use cases, but the alternative and key conditional usage are explicit.

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

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

Annotations already flag destructiveHint=true, but the description adds substantial context beyond that: the operation is irreversible, only /trash or /photos-trash paths are accepted, the CLI can only address trashed items by name, and ambiguous names trigger a refusal that returns uids.

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 irreversible warning and required flag are front-loaded and every sentence carries actionable information. It is slightly dense with parenthetical clauses, but nothing is 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 destructive 3-parameter tool with no output schema, the description covers prerequisites, failure modes, safety gating, and fallback advice, 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?

Schema coverage is 100%, so the baseline is 3; the description adds operational meaning by tying uid to drive_list_trash and requiring confirmed=true as an explicit user acknowledgment. It also surfaces the name-collision constraint that makes path vs uid selection non-trivial.

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 (permanently delete a file or folder) and immediately scopes it to items already in the trash, marking it irreversible. This cleanly separates it from siblings drive_trash (soft delete) and drive_empty_trash (bulk wipe).

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 prescribes the workflow: drive_trash first, then pass the trash path or a uid from drive_list_trash. It also names when to abandon the tool entirely (duplicate trashed names — use the web/desktop app) and requires confirmed=true with the path shown to the user first.

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 behavior the annotations do not: folder downloads recurse, the return shape is {downloaded, skipped, failed} rather than a path, the call fails if any file fails, and the destructive 'remove' path deletes the LOCAL item and is gated by confirmed=true. This is exactly the kind of mutation/confirmation nuance the agent needs, and it does not contradict the destructiveHint=false default since deletion is opt-in and user-approved.

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-loads the core purpose, then layers the tricky localPath semantics, recursion, defaults, return shape, and confirmation gate. No filler; every sentence carries an operational fact.

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 describing the return counts and failure behavior, and it covers recursion, conflict defaults, and confirmation requirements. An agent has everything needed 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 baseline is 3; the description goes further by clarifying that localPath is a destination FOLDER with a concrete worked example ('/my-files/report.pdf' with '/tmp/out' yields '/tmp/out/report.pdf') and by restating the confirmed gating condition. That added meaning, especially the example, exceeds the schema text.

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 ('Download a file or folder from Proton Drive to the local filesystem'), and the scope (file vs folder, recursive) distinguishes it from siblings like photos_download, drive_read_file, and drive_sync_plan. An agent can identify it without opening the schema.

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

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

Gives clear operational context: when confirmed=true is mandated ('remove' strategies that delete the local item), and that file/folder conflict strategies are separate and default to 'skip'. It stops short of explicitly naming when to prefer this over drive_read_content or drive_sync_plan, so routing between siblings remains inferential.

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 flag destructiveHint=true; the description goes further by naming the irreversibility, the mandatory confirmed=true gate, and the review-before-confirm protocol. This is real behavioral context an agent needs before firing a bulk-destructive call.

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

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

Three short sentences, front-loaded with the destructive scope, then the precondition, then the sibling routing. No filler, every clause earns its place.

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

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

For a one-parameter, no-output-schema bulk-destructive tool, the description supplies scope, irreversibility, the confirmation requirement, and the safe operating procedure. Nothing an agent needs 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% and the single parameter already carries a description ('Must be true; the user has reviewed the trash...'), so the description's restatement of 'Requires confirmed=true' adds nothing new. Baseline 3 is correct when the schema does the work.

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

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

States a specific verb ('Permanently delete') plus resource and scope ('ALL items in the Proton Drive trash'), and immediately marks the operation as irreversible. It also distinguishes itself from the two nearest siblings, drive_delete (individual items) and drive_list_trash (review step).

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

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

Gives an explicit pre-call workflow ('Call drive_list_trash first, show the user exactly what will go, and get explicit confirmation') and names the alternative for the other case ('For individual items use drive_delete'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description adds substantial beyond that: verify writes temporary local files that are removed afterwards, it never deletes anything, results may be candidate-only, the walk is cached up to 5 minutes, and a first large-drive walk can take minutes. These are exactly the operational traits an agent needs.

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 compact sentences, front-loaded with the detection rule, then verification side-effects, then reporting, then caching. Every clause carries information; nothing is restated from the 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?

With no output schema and seven optional parameters, the description supplies the missing context: what is returned (groups, wastedBytes, suggested keeper), the safety guarantee against deletion, and the performance characteristics that affect how an agent should call it.

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, but the description adds meaning the schema lacks: verify actually downloads and sha256s files (not just a boolean), and refresh is tied to the cached-walk behavior. It also names the reported fields (wastedBytes, suggested keeper), which maps conceptually to the output rather than 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?

States a specific verb and resource ('Find likely duplicates') and immediately defines the detection heuristic (same sha1, or same size+mediaType when sha1 is absent). No sibling tool overlaps this purpose, and the candidate-vs-verified distinction is clear.

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?

Explains when results are only candidates and when verify=true upgrades them to 'verified', plus the refresh/cache tradeoff, which tells an agent when to re-walk vs reuse. It stops short of explicitly comparing to a sibling or stating exclusions, but no sibling is close enough to warrant it.

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

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

Annotations only declare readOnlyHint and idempotentHint; the description adds substantial behavioral context beyond them — that sha1 is uploader-claimed, unverified and often absent, that verification wrappers are unwrapped and noise fields dropped, and that verbose=true returns a raw CLI node with no guaranteed shape.

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 purpose and tightly packed with useful detail; the parenthetical on verbose and the sha1 caveat both earn their place. Slightly dense, but no sentence is 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?

There is no output schema, so the description carries the return-value burden and does so by naming the specific fields returned (mtime, uploadedAt, sha1) and their caveats. An agent has everything needed to call and interpret the result.

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, but the description adds real meaning to verbose by explaining it returns an unguaranteed raw CLI node versus the trimmed default. The path parameter adds nothing beyond the schema's own example, so it is not a full 5.

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?

Names a specific verb and resource ('Get full metadata for one Proton Drive file or folder') and scopes it to a single item, with a closing pointer to drive_list for enumeration. An agent can distinguish it from the many sibling drive tools without opening the schema.

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

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

Explicitly routes enumeration to drive_list, which is the key adjacent use case. It does not address when to prefer this over drive_read_file/drive_read_content, but for a metadata-only read tool the guidance 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?

Annotations only carry destructiveHint=false; the description adds the meaningful post-condition that the folder becomes visible in Drive, which the annotation does not convey. It stops short of stating auth requirements or what happens if the invitation is already accepted/expired.

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 tight sentences, outcome and sourcing constraint front-loaded, with no filler or redundant restatement of the tool name.

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 single-parameter, non-destructive action with no output schema, the description covers purpose, effect, and parameter sourcing adequately. Minor omissions (auth state, behavior on an invalid/already-accepted uid) keep it short of a 5.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine value beyond the schema by specifying the authoritative source of the uid and forbidding guessing it, reducing copy-paste/hallucination errors.

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 ('Accept a pending sharing invitation') and describes the resulting observable state ('the shared folder then appears in your Drive'), which cleanly distinguishes it from the sibling drive_invitation_reject.

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 directs the agent to obtain the uid from drive_list_invitations and warns 'never guess it', naming the source tool. It lacks an explicit when-not or a failure-path note, but the routing guidance is clear enough to act on.

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; the description adds substantial context beyond that — the rejection is permanent, the sender is NOT notified, and a confirmation flag plus user approval is required. These are the behavioral facts that actually change how an agent should call this.

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 tight clauses, front-loaded with the action and its irreversibility, then the uid sourcing rule, then the approval gate. No filler sentences.

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 destructive tool with no output schema, the description covers sourcing, irreversibility, notification behavior, and the approval gate, so an agent can act safely. Only marginal gaps remain (e.g., what happens if the invitation is no longer pending), which are not essential.

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

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

Schema description coverage is 100% and both parameters are already documented there (uid source, confirmed must-be-true-after-approval). The description reinforces but does not extend the schema's parameter meaning, so the baseline 3 applies.

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

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

Specific verb+resource ('Reject a pending sharing invitation') with a stated scope ('pending', 'permanently') that clearly distinguishes it from drive_invitation_accept and drive_share_leave. An agent can select it without opening any 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 preconditions and alternatives: get the uid from drive_list_invitations ('never guess it'), and confirmed=true only after explicit user approval. This is exactly the when/how guidance an agent needs for a destructive action.

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 establish read-only/idempotent, yet the description discloses pagination behavior (default limit 200, offset, hasMore), stable sorted order, the caveat that each page is a fresh read so items can shift between page calls, and the important trust caveat that sha1 is a claimed, unverified, often-absent hash. These are real behavioral traits not derivable from the annotations or schema.

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

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

Front-loads the core operation and scope in the first clause, then layers return shape and caveats in a logical order. It is dense and one parenthetical field list is long, but every element carries information an agent needs given 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?

With no output schema, the description fully carries the return contract: the response envelope, item field meanings, sorting, pagination, and the trust caveat on sha1. Combined with the read-only annotations, an agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 100%, so all four parameters are already documented, including the type enum and limit/offset defaults. The description's field-level explanation (storageSize, mtime, uploadedAt, sha1) describes returned items rather than refining parameter meaning, so it adds little on this axis beyond the schema 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?

States a specific verb and resource ('List the immediate children of a Proton Drive folder') and immediately bounds the scope with '(one level, not recursive)', which also separates it from the recursive drive_tree sibling. The note that listing '/' returns top-level roots removes the main ambiguity about the path parameter's root case.

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 routes trash browsing to drive_list_trash and clarifies the non-recursive scope, so the agent knows when not to use it. It does not, however, contrast against drive_tree or drive_search, which an agent might reasonably confuse it with given 48 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 declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds real behavioral context beyond that: results are filtered to pending invitations and only those from other users, and it clarifies that the entries carry a uid usable by the accept/reject siblings. Pagination or ordering behavior is not described.

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, with the operation front-loaded and the field shape rendered compactly as an inline record list. The field list is dense but each entry earns its place given there is no output schema; no filler text.

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

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

With no output schema, the inline field list (uid, role, invitedByEmail, invitedAt?, nodeName, nodeType) supplies exactly the return-value information an agent needs, including an optionality marker. Combined with the follow-up routing, nothing material is missing for a zero-parameter list 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 tool takes zero parameters, so the baseline is 4. There is nothing for the description to disambiguate on the input side.

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) and resource (pending sharing invitations from other users), with scope qualifiers that separate it from drive_share_status, drive_sharing_audit, and the invite/accept/reject siblings. An agent can identify the operation without opening any 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?

Explicitly routes the agent to the follow-up tools (drive_invitation_accept / drive_invitation_reject) and names the field (uid) needed to call them, which defines this tool's place in the flow. It stops short of stating when NOT to use it or any prerequisites, so it does not reach the top band.

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

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

Beyond the readOnly/idempotent annotations, it discloses sort order and tie-breaking (newest first, ties by uid), default page size, the fact that each page is a fresh read so items can shift between calls, and that names are non-unique so uid+trashedAt must disambiguate. It also flags that restore/delete refuse shared names — genuinely 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?

Dense but front-loaded, leading with what it does and the return shape before the caveats. Slightly packed with detail, but each clause (ordering, non-unique names, uid caveat) 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?

With no output schema, the description fully describes the return shape ({items, total, offset, limit, hasMore}) and item fields, plus pagination caveats. An agent has everything needed to call and interpret 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 coverage is 100%, so the two parameters (limit, offset) are already documented in the schema; the description mostly repeats the default limit and adds sorting detail rather than new parameter syntax. 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?

States a specific verb and resource ('List all files and folders in the Proton Drive trash'), which distinguishes it from the sibling drive_list that lists non-trashed content. An agent can identify the operation without opening the schema.

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

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

The context is clear (this is trash listing, as opposed to drive_list), and it helpfully routes the agent by noting that drive_restore/drive_delete consume the returned uid. It does not explicitly state 'use drive_list for live files', but the framing makes the alternative inferable.

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 annotations covering only destructiveHint=false, the description carries the behavioral burden well, disclosing the two failure conditions (existing folder, missing parent) and the non-recursive mkdir semantics. This is precisely the pre-invocation knowledge an agent needs to avoid a predictable error.

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 tight sentences, front-loaded with the core action and followed immediately by the failure/recursion caveats. No filler or redundant restatement of the tool name.

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 single-parameter, no-output-schema creation tool, the description covers purpose, failure modes, and recursion behavior. Nothing an agent needs in order to call this 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% and the path parameter is already documented with an absolute-path example, so the schema does the heavy lifting. The description adds no additional syntax, format, or constraint detail beyond what the schema provides, which is the expected baseline for a single well-documented 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?

States a specific verb and resource ("Create a new empty folder on Proton Drive"), which unambiguously distinguishes it from sibling mutation tools like drive_rename, drive_move, and drive_copy. An agent knows exactly what operation this performs without opening the schema.

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

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

The description gives clear operational context: it fails when the folder exists or the parent is missing, and it explicitly instructs the caller to create each level separately rather than relying on recursive creation. It does not name an alternative sibling for recursive creation (none appears to exist), so it stops short of a full when/when-not comparison.

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 destructiveHint=false, so the description carries most of the burden and does well: it discloses the two failure modes (destination occupied, parent missing) and the full-path requirement. It doesn't say what happens to an existing target or whether the operation is reversible/overwriting, but the added context is solid.

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 tight sentences, zero waste, with the core behavior front-loaded and the alternative/edge cases trailing. Every sentence earns its place.

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

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

With no output schema and minimal annotations, the description adequately covers action, semantics, failure modes, and an alternative. Only the omission of a pointer to drive_rename and any note on overwrite/reversibility behavior leaves a small gap.

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

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

Schema description coverage is 100%, so baseline is 3, but the description genuinely adds semantics the schema doesn't: destinationPath is the FULL new path, not the parent, and the rename-vs-move distinction follows from that. This is real meaning beyond the raw field docs.

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

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

States a specific verb+resource ('Move or rename a file or folder') and immediately clarifies the overloaded behavior that distinguishes it from a plain rename tool: same parent + new filename renames, different parent moves. An agent can tell exactly what this 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?

Names the alternative explicitly ('To keep the original use drive_copy') and gives the condition that selects it, plus the failure conditions (destination occupied, parent missing). It does not address the sibling drive_rename, which is the closest potential source of confusion, keeping it just short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), but the description adds real value beyond them: the 10 MB limit, the paging model, the format whitelist, and an explicit prompt-injection warning that file content is untrusted data. Only the pagination continuation behavior is left mostly implicit.

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

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

Three dense sentences, front-loaded with the core action and constraints; every clause (formats, size cap, paging, untrusted content) carries information and none is wasted.

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 still conveys the return shape through the paging hint and nextOffset reference in the schema. For a read tool whose annotations already carry safety, this is close to complete; only explicit terminal/pagination semantics for the last page are missing.

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

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

Schema description coverage is 100%, so path, offset, and maxChars are already fully documented with defaults and bounds. The description only restates 'paged by offset/maxChars' without adding format or edge-case detail, so baseline 3 applies.

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

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

Clear verb+resource (read text of a Drive file) with explicit supported formats and a size bound. It does not differentiate itself from the sibling drive_read_file, which an agent must disambiguate on its own, so it falls short of a 5.

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

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

It states a key precondition ('without a sync folder') and supported file types, which implies when it applies, but there is no explicit when-to-use guidance versus drive_read_file or drive_download, and no stated exclusions for unsupported types.

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 cover the safety profile (readOnly, idempotent, not open-world), and the description adds substantial context beyond them: the 1 MB cap, the UTF-8-only constraint, the required environment variable and running desktop app, and which input classes produce errors. This is exactly the runtime behavior an agent cannot infer from annotations.

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

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

Three dense sentences: what it reads, what it requires, and what fails. Constraints and prerequisites are front-loaded and every clause carries information, with no filler.

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

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

For a single-parameter read tool with no output schema, the definition covers prerequisites, limits, and failure modes well. It never states that the return value is the decoded file text (or how the content is framed), which is the one remaining inference an agent must make.

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 path parameter's format, /my-files mapping, and relative-path fallback are already fully documented in the schema. The description adds no path syntax or format detail beyond it, so the baseline 3 applies.

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

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

States a specific verb (Read), resource (UTF-8 text file), scope (max 1 MB, local Proton Drive sync folder), and explicitly names the sibling it is not for unsupported inputs (drive_download). An agent can distinguish it from drive_download 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?

Gives explicit preconditions (PROTON_DRIVE_SYNC_PATH set, desktop app running, file synced) and a clear when-not rule routing binary, non-UTF-8, or oversized files to drive_download. It does not, however, address the closer sibling drive_read_content, leaving one plausible alternative unmentioned.

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 destructiveHint=false annotation already tells the agent this is a non-destructive operation, so the description only needs to add context beyond that. It does add the meaningful 'same parent' constraint, but says nothing about collision behavior — e.g. whether renaming to an existing name fails, overwrites, or auto-suffixes — which is the key behavioral unknown for a rename tool.

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

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

Two sentences, zero filler, with the scope constraint front-loaded and the alternative routing second. Every clause earns its place.

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

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

For a simple two-parameter, no-output-schema operation, the description covers purpose, scope, and the sibling alternative adequately. The only real gap is the undefined behavior when the target name already exists.

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 both parameters (path, newName) are already documented in the schema, including the important 'not a path — just the name' clarification. The description adds no parameter detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (rename) and resource (file or folder), plus the scoping constraint 'in place (same parent)', which distinguishes it from a move operation. An agent can identify this tool without opening the schema.

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

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

Explicitly names the alternative ('To change folders use drive_move') and the condition that selects it. The when-not guidance is unambiguous, which is unusually strong for a sibling set this large.

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 give only destructiveHint=false, so the description carries the real load: it discloses the refusal on duplicate names, the CLI's name-only addressing limitation, and two failure conditions (original parent gone, same-named item at the target path).

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 tight sentences, front-loaded with the action and its scope; the constraints and alternative follow in order of relevance, with no filler.

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

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

For a two-optional-parameter restore tool with no output schema, the description covers what an agent needs to call it correctly and what will make the call fail.

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

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

Schema description coverage is 100% and both parameters are already documented, including the path/uid match rule. The description adds only the contextual note that the CLI addresses trashed items by name, 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?

States a specific verb ('restore') and resource ('trashed file or folder') plus the destination ('original Proton Drive path'), which cleanly separates it from siblings like drive_trash, drive_empty_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 routes the agent to drive_list_trash to obtain the path/uid, and names a genuine alternative (Proton Drive web or desktop app) for the ambiguous-name case where this tool refuses.

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 annotations providing readOnlyHint=true and idempotentHint=true, the safety profile is covered. The description adds significant behavioral context beyond annotations: cache duration (5 min), cache-bypass mechanism (refresh=true), path exclusions (.git/node_modules), timeout behavior (25s partial results with partial:true), index behavior (PROTON_DRIVE_INDEX=1 may cause stale:true), and the meaning of walk.complete=false. These are valuable operational details not visible in the schema or annotations.

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

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

The description is a single dense paragraph that front-loads the core purpose, then immediately covers the return shape and critical behavioral caveats. Every sentence provides actionable information: the return structure, cache behavior, timeout handling, and index behavior. No padding or repetition.

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

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

Given 14 parameters with full schema coverage, no output schema, and annotations covering safety, the description is remarkably complete. It explains the return structure, cache and timeout behaviors, index interaction, and operational failure modes (partial:true, walk.complete=false, stale:true). An agent has enough information to call this tool correctly and handle its responses.

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 all 14 parameters with examples and constraints. The description adds one important semantic detail: 'Filters are ANDed', which clarifies how multiple filter parameters combine. However, it doesn't add format details or edge cases for individual parameters beyond what the schema provides.

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

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

The description opens with a specific verb+resource combination ('Find files/folders under a path') and explicitly lists the filter dimensions available (name, type, extension, size, date). This clearly distinguishes it from siblings like drive_list (which presumably lists without filtering) and drive_tree (which shows hierarchy). The 'in one walk' phrase hints at a single-traversal approach, though the distinction from drive_list isn't explicitly stated.

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 conditions for using advanced features: 'refresh=true re-reads' when cache is stale, 'call again' when partial:true is returned, and 'repeat the call or pass refresh:true' when index-based results are stale. However, it does not explicitly state when to use drive_search vs drive_list or drive_tree, nor does it say when NOT to use this tool. The guidance is operational rather than comparative.

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 openWorldHint and destructiveHint=false; the description adds crucial behavior the annotations do not: an email is sent immediately, a duplicate invite may silently overwrite the existing role, and confirmed=true is mandatory after user approval. This is exactly the kind of side-effect disclosure an agent needs.

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, then constraints, then role meanings. Every sentence carries behavioral weight, though the role listing mildly duplicates the enum descriptions already in the 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?

With no output schema and a mutation-style tool, the description supplies the missing pieces: side effects, the overwrite risk, required confirmation, and cross-tool sequencing. Nothing essential for correct invocation is absent.

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

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

Schema coverage is 100%, so all five parameters including the role enum and confirmed flag are already documented in the schema. The description largely restates the role meanings and confirmed requirement rather than adding new parameter-level semantics, so the baseline 3 applies.

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

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

States a specific verb (invite) plus resource (a person, by email, to a Proton Drive file or folder), so an agent knows exactly what the tool does. It is clearly distinguishable from siblings like drive_share_status and drive_share_revoke.

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

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

Gives explicit prerequisites and sequencing: confirm address and role with the user first, run drive_share_status beforehand to avoid a silent overwrite, and only call after explicit user approval with confirmed=true. It names the alternative tool and the condition selecting it.

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

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

Annotations declare destructiveHint=true, but the description adds valuable context the annotation cannot: the blast radius (owner and other members unaffected) and the approval-gated confirmation requirement. It stops short of describing failure modes (e.g. what happens if path isn't a shared folder or isn't owned by someone else).

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 tight clauses: action+scope, alternative routing, and prerequisite. Zero waste, and the action is front-loaded before the routing advice.

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

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

For a 2-parameter mutation with no output schema, the description covers purpose, routing, blast radius, and the confirmation gate. Only minor gaps remain (error behavior if path is not a shared folder), which is defensible given the rich schema text.

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 including path format and the confirmed semantics are already fully documented in the schema. The description reinforces the confirmed requirement but adds no syntax or format detail beyond it, matching the baseline 3.

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

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

Specific verb+resource ('Leave a Proton Drive folder shared with you') with an explicit scope boundary stating the owner and other members are unaffected. It also names the sibling it is not (drive_share_revoke), so an agent can distinguish it immediately.

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

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

Explicitly routes the agent: 'For your own folders use drive_share_revoke', and states the prerequisite 'Requires confirmed=true after explicit user approval.' Both when-to-use and the alternative are named.

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 destructiveHint=true, it discloses the blast radius (every member plus pending invitations, Proton and non-Proton, in one call) and a boundary the annotation cannot express: it does NOT remove a public link, and the result reports whether one is active. That is exactly the kind of extra context annotations cannot carry.

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

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

Three short sentences, each earning its place: scope, prerequisite/sequencing, and exclusions with the sibling to use instead. The scope constraint 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 destructive, two-parameter tool with no output schema, the description covers scope, prerequisite, sequencing, and exclusion behavior. An agent has everything needed to call it safely and correctly.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description reinforces the confirmed=true requirement but adds no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a precise verb and scope: removing access for every member and pending invitation (Proton and non-Proton) on a shared path in one call. It is immediately distinguishable from drive_share_revoke (one person) and drive_share_remove_url (public link).

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

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

Explicitly names the prerequisite (confirmed=true), the recommended preparatory step (run drive_share_status first), and both alternatives for adjacent cases, with the condition that selects each. 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 already flag destructiveHint=true, and the description adds meaningful context beyond that: the link stops working immediately and member access remains intact, plus the confirmation gate. It doesn't note irreversibility details or whether the link can be recreated, but the added behavioral detail is solid.

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

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

Three short clauses, front-loaded with the action and effect, then the safety gate. No filler sentences.

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?

A simple two-parameter mutation with no output schema; the description covers effect, scope, and the confirmation requirement, which is everything an agent needs 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 description coverage is 100%, so both 'path' and 'confirmed' are already documented in the schema. The description reinforces the confirmed=true requirement but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Remove the public share link from a file or folder') and scopes it precisely enough to distinguish it from siblings like drive_share_remove_all and drive_share_set_url.

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 a clear precondition ('Requires confirmed=true after explicit user approval') and clarifies the blast radius ('Member access is unaffected'), which tells the agent this targets only the public link. It does not explicitly name an alternative tool for bulk removal, so it falls short of a 5.

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

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

Annotations only supply destructiveHint=true, and the description adds substantial context beyond that: the target is not notified, pending invites are included, the operation fails on a non-member address (case-insensitive match), and confirmed=true is required only after explicit user approval. This is exactly the behavioral disclosure a destructive mutation needs.

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 short sentences, front-loaded with the action and scope, then prerequisites, then alternatives. Every sentence carries a distinct decision-relevant fact; nothing is redundant with the title.

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, no-output-schema mutation with thin annotations, the description covers what is destroyed (one member's access), what is not (no notification), failure modes, prerequisites, and the approval gate. Nothing needed to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the email must correspond to a current member or invitee (case-insensitive) and 'confirmed' is a deliberate user-approval gate rather than a plain boolean. Format details for path remain with 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 and resource — removing one person's access to a Proton Drive file or folder — and immediately scopes it to 'one person,' which separates it from drive_share_remove_all and drive_share_leave. An agent can select it correctly without opening any 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?

Explicitly routes the agent: verify the address with drive_share_status first, use drive_share_remove_all to remove everyone, and revoke-plus-re-invite to change a role. Both prerequisites and alternatives are named, with the condition that selects each.

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 idempotentHint=false, and the description independently justifies both: repeated calls replace link settings rather than no-op, and omitting password/expiration silently removes them, producing a warning. It also discloses the ~90-day expiration cap and the security exposure that the password is passed as a CLI argument visible in the process list and shell history — none of which the schema or annotations convey.

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?

Purpose and audience come first, then the replace/warning behavior, then constraints (expiration cap), then return shape, then the security caveat and approval gate. Every sentence carries distinct, load-bearing information with no repetition of name or title.

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 mutation tool with no output schema, the description supplies the return shape inline ({url?, role?, expirationTime?, warning?}, fields may be absent), the mutation and replacement semantics, the confirmation gate, and the security caveat. Nothing an agent needs 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%, so the baseline is 3, and the description exceeds it by explaining semantics the schema cannot: the ~90-day expiration ceiling, the destructive meaning of omitting password/expiration on re-call, and the CLI-visibility risk of the password value. It stops short of spelling out the return-field shapes per parameter, which keeps it from a 5.

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 ('Create or update a public share link') and immediately defines the scope: anyone with the link, no Proton account needed. It also names the sibling it is not, drive_share_invite, so an agent can route between public-link and private-invite paths 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 ('anyone with the link', no account needed) and a named alternative for the other case ('For private sharing use drive_share_invite'). It further flags the re-invocation semantics (calling again REPLACES settings) and the confirmed=true approval prerequisite, which is exactly the kind of gating an agent needs before calling.

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 description's 'Read-only' restates the structured field. What it adds is genuinely useful and not in the annotations: that members includes pending invitations, possibly to non-Proton addresses, and that the status field must be checked to interpret them.

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

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

One dense but well-front-loaded block: return shape first, then the pending-invitation caveat, then the usage rule. Every clause carries information an agent needs, with no filler.

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

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

With no output schema, the description carries the burden of describing return values and does so explicitly (isShared, members with email/role/addedAt/status, shareUrl). Combined with annotations covering safety and the schema covering the single parameter, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the path parameter is fully documented in the schema, including format and example, so the description does not need to explain it. The description adds no additional parameter meaning beyond what the schema already provides; baseline 3 applies.

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

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

States a specific verb+resource ('Return the sharing state of a Proton Drive path') and enumerates the returned shape, so the agent knows exactly what it gets. It also names the siblings it relates to (drive_share_invite, drive_share_revoke), making it distinguishable without opening other 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 prescribes ordering and purpose: call before drive_share_invite to avoid duplicates and before drive_share_revoke to confirm the email address. Both the when and the why are stated, with the alternative tools named.

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 safety is covered structurally. The description adds genuinely useful behavioral context beyond that: a hard 100-item cap, that URLs are deliberately omitted, and how each risk flag is defined. It does not explain pagination or what happens past the 100-item limit.

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

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

Dense but front-loaded: the verb and scope come first, then the returned fields and risk flags in a compact list. Every clause carries information, though the parenthetical enumeration is slightly crammed and could be split for scanability.

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 carries the full burden of describing returns and does so by listing public links, invitees, pending invitations, and named risk flags. The main remaining gap is the absence of any guidance on result ordering, pagination, or behavior when the 100-item cap is hit.

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 (path default, refresh meaning) are documented in the schema itself, so the description adds no syntax or format detail beyond it. Per the baseline rule for high coverage with no compensating parameter info, a 3 is correct.

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

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

States a specific verb+resource ("Audit sharing under a path") and immediately enumerates what the audit covers, so an agent can tell it apart from read-only status tools like drive_share_status or drive_list_invitations. It stops short of naming a sibling it is not, so it is clear but not fully disambiguated.

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

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

Usage is implied by the name and the enumeration of audited sharing artifacts, but there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as drive_share_status for a single item. The scope ("under a path") hints at the context but does not state it as guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description goes well beyond them: it defines the diff categories (only local, only Drive, changed), the 'maybe changed' tolerance rule (same size, mtime >2s apart), that symlinks are skipped, and that byte totals and completeness are computed. This is exactly the behavioral detail an agent needs and the annotations cannot supply.

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?

Extremely dense but front-loaded: the safety statement ('Read-only plan, transfers nothing') leads, followed by the diff semantics. Every clause carries information and there is no filler.

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

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

With no output schema, the description usefully outlines the return content (diff categories, byte totals, completeness). It covers the core read-only semantics and side effects, leaving only minor gaps such as pagination/limit behavior, which the schema already supplies.

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 limit, ignore, compare, and direction. The description adds meaningful semantics for the comparison result ('maybe changed' at >2s mtime skew) but says nothing about limit, ignore globs, or direction, so it adds only marginal meaning beyond structured fields.

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

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

The description names a specific verb and resource — 'diff a local folder against a Drive folder' — and immediately states the scope ('Read-only plan, transfers nothing'). No sibling tool does local-vs-Drive comparison, so it is unambiguous without opening the schema.

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

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

'Read-only plan, transfers nothing' implicitly signals this is the preview step before an actual transfer, which is useful context. However, it never states when to use this versus a direct operation, nor names a follow-up or alternative tool, so guidance is only implied.

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 idempotentHint=true and destructiveHint=false, which the description correctly reinforces rather than contradicts. The description adds real behavioral context beyond the annotations: the path disappears immediately but the item is recoverable via drive_restore. It stops short of describing response shape or any auth/permission requirements, so it is strong but not exhaustive.

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

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

Three short sentences, zero waste, and the core action plus the recoverability/preference guidance are front-loaded. Every sentence earns its place.

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

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

For a single-parameter, non-destructive move tool with no output schema, the description covers what an agent needs: what it does, what happens to the path, how to undo it, and when to prefer it over deletion. Nothing material 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?

Only one parameter exists and schema coverage is 100% ('Absolute remote path to trash.'), so the schema carries the semantics. The description adds no syntax or format detail beyond what the schema provides, which is the expected 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?

States a specific verb and resource ('Move a file or folder to the Proton Drive trash') and distinguishes itself from siblings by naming drive_restore (the inverse) and drive_delete (the permanent alternative). An agent can pick it apart from drive_delete and drive_empty_trash without opening any 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?

Explicitly routes the agent: 'Prefer this over drive_delete unless the user explicitly wants permanent removal.' It names the alternative tool and the condition that selects it, leaving nothing 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 readOnly/idempotent annotations, the description discloses substantial behavior: exact return shape, that totals cover only opened folders, the meaning of 'unexpanded' (depth limit, .git/node_modules, failures), that complete=false signals partial failure, and a 5-minute cache with a refresh override. This is rich, non-obvious context an agent could not get from the structured fields.

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 purpose, then the return shape, then edge-case and cache behavior. Every sentence carries information. It is dense and the brace-enumerated return list is terse, which keeps it just short of maximally clean, but there is no filler.

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

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

With no output schema, the description carries the burden of explaining return values and it does so fully: field list, totals semantics, unexpanded/complete flags, and caching. Combined with annotations covering the safety profile, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that depth limits cause folders to be counted as 'unexpanded' rather than expanded, and that refresh bypasses a 5-minute cache. That causal context for depth and refresh goes past the terse schema descriptions.

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

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

The description states a specific verb+resource: a folder overview returning a tree with per-folder file counts and size totals, sorted largest first. This is clearly distinguishable from flat siblings like drive_list or drive_info by the aggregate/tree framing. It stops short of naming an alternative explicitly, so it lands at 4 rather than 5.

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

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

Usage is implied rather than stated: an agent can infer this is the tool for an aggregate folder overview vs a flat listing. The caching note ("Cached 5 min; refresh=true re-reads") is operational guidance, but there is no explicit when-to-use-this-vs-drive_list/drive_usage routing or stated 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?

Annotations only declare openWorldHint and destructiveHint=false; the description adds substantial behavior beyond them — return shape {uploaded, skipped, failed}, failure on failed>0 with quota/destination-not-found examples, separate file/folder conflict defaults of 'skip', and the fact that 'replace' trashes the existing remote item. It does not cover permissions or progress/partial-failure nuance, so not a full 5.

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-loads purpose first, then return/failure semantics, then conflict strategies, then the confirm gate. Every sentence carries information, though the density (multiple parentheticals and semicolon clauses) makes it slightly heavier than necessary.

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?

No output schema exists, yet the description supplies the return shape and failure condition; the confirmation prerequisite, destination-folder requirement, and conflict-strategy defaults are all stated. Nothing an agent needs to invoke this 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%, so the baseline is 3; the description adds a cross-parameter relationship the schema does not state — that fileConflictStrategy and folderConflictStrategy are distinct (CLI v0.8.0+), both defaulting to 'skip', and that 'replace' triggers the confirmed=true requirement. That coupling is genuine added meaning beyond the per-field enum docs.

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

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

States a specific verb+resource ('Upload a local file or folder to Proton Drive') with scope details (recursive folders, end-to-end encryption). It also distinguishes itself from siblings drive_write_file (text) and drive_mkdir (destination creation), so an agent can route correctly without opening schemas.

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

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

Explicitly names alternatives and the conditions that select them: use drive_write_file for text, drive_mkdir to create the destination, and require confirmed=true when a conflict strategy is 'replace'. Both when-to-use and when-not-to-use are covered.

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

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

Goes well beyond the readOnlyHint/idempotentHint annotations: discloses the 5-minute cache and that other clients' changes are invisible until expiry, that refresh=true bypasses it, that trash stats are always uncached (~2.5 s), that a first walk of a large drive can take minutes, that sizes are summed file sizes rather than quota, and that `complete` flags partial results.

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

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

Dense but well front-loaded: the report contents come first, then cost/cache caveats, then the `complete` flag. It is a long single paragraph, but nearly every clause carries operational information rather than 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?

With no output schema and a 4-param read tool, the description compensates by describing what the report contains and calling out the `complete` partial-results flag, plus latency and cache behavior. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: it explains what `refresh` interacts with (the cached walk), frames `path` as a subtree root, and ties `olderThanDays` to the old-files section. It does not restate the top/path defaults already 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?

States a specific verb+resource (storage analytics over a subtree) and enumerates the report contents: totals, largest files/folders, extension/media breakdown, old files, trash stats. This clearly separates it from siblings like drive_info, drive_tree, and drive_find_duplicates.

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 clear context for use (analytics on a subtree) and notes the trash-stats cost and cache staleness, but never explicitly names an alternative tool or a when-not-to-use condition. Implicit routing is strong, explicit routing is absent.

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, idempotentHint and non-open-world, so the safety profile is covered. The description still adds value beyond them by disclosing that no authentication is required and what the response payload looks like.

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?

One tight sentence that front-loads the resource and return shape, then appends the auth and usage caveats. Nothing is padded or repeated.

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 diagnostic with no output schema, the description supplies everything needed: what it returns, its shape, that it needs no auth, and why an agent would call it instead of another 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 tool takes no parameters, so the baseline is 4 and there is nothing for the description to compensate for. It correctly avoids inventing parameter semantics that do not exist.

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: returns the installed proton-drive CLI and SDK versions, and even names the return shape {cli, sdk}. It is not explicitly differentiated from the nearest-sounding sibling drive_info, which is the only remaining ambiguity.

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 clear usage context ('use to confirm the binary or diagnose compatibility') and a prerequisite ('Needs no authentication'). No alternative tool is named or excluded, so it stops short of full when/when-not 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 only declare destructiveHint and openWorldHint; the description adds the substantive context they don't: the 5 MB cap, that no Proton login is needed, the required local env var, the dependency on the running desktop app for cloud sync, local parent-directory creation, and the refuse-to-overwrite safeguard. This is exactly the extra behavioral layer expected when annotations cover only the safety flags.

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

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

Front-loaded and generally tight, but the overwrite rule is stated twice — 'Refuses to overwrite an existing file unless confirmed=true — ask the user first' and 'Requires confirmed=true when the file already exists (it would be overwritten)' — so one sentence is pure duplication.

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 mutation tool with no output schema, the description covers the environment prerequisites, size limit, path scoping behavior, and the confirmation gate, which is everything an agent needs to invoke it safely. The annotated destructive/open-world hints are also consistent with the described overwrite behavior.

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, but the description adds workflow meaning the schema doesn't: confirmed must be supplied when the file already exists because it would be overwritten, and the agent should get user approval first. It doesn't restate path syntax (correctly deferring to the schema), so it stays additive rather than redundant.

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 ('Write text ... to a file in the local Proton Drive sync folder') and immediately scopes it against siblings by naming drive_upload for binary content and implying drive_read_file is the read counterpart. An agent can distinguish it from drive_mkdir, drive_upload and drive_rename without opening any 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 and when-not: text only (max 5 MB), use drive_upload for binary, requires the desktop app running and PROTON_DRIVE_SYNC_PATH set, and must not overwrite without user approval. It also tells the agent to ask the user first, which is a usable behavioral rule.

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 are minimal (destructiveHint: false), so the description carries most of the burden, and it does add real behavioral context: the photo must already exist in the library and nothing is uploaded. It still omits what happens if the photo is already in the album or the album path is invalid (idempotency/error semantics).

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 short sentences, front-loaded with the core action and the clarifying '(does not upload)' constraint before the sibling pointer. No filler.

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

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

For a two-parameter tool with fully documented schema and no output schema, the description covers purpose, precondition, and the sibling needed to resolve the album path. Only error/idempotency behavior is left unstated, a minor gap.

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

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

Schema description coverage is 100%, with both albumPath and photoPath documented in the schema. The description adds no path syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (add) and resource (photo to album), and explicitly disambiguates from upload with '(does not upload)'. An agent can distinguish it from photos_upload without opening any 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?

Points the agent to photos_list_albums to obtain a valid album path and clarifies a precondition (photo must already be in the library). It provides clear context but does not mention the inverse sibling photos_remove_from_album or note when this operation is not 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?

With only destructiveHint=false provided, the description carries most of the burden and does so well: it discloses that the album is created empty, that it is placed at /albums/<name>, and that the call fails if the name already exists. It stops short of mentioning auth requirements or what the response contains.

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 short sentences, zero waste, with the core action and the name-not-path constraint front-loaded before the edge case. Every clause earns its place.

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

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

For a one-parameter, no-output-schema tool this covers the essential facts: what is created, where, and the failure mode. Minor gaps (auth context, duplicate-name alternatives like opening the existing album) remain but are not critical.

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, but the description adds genuine meaning with 'Pass the name, not a path', clarifying that the value is a bare label rather than a location. That is a real disambiguation the schema alone does not make.

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 ('Create an empty Proton Photos album'), which clearly separates it from photos_list_albums and photos_delete_album. It does not explicitly name a sibling to disambiguate against, which keeps it at 4 rather than 5.

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

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

Usage is implied by 'create an empty album' and by the failure condition, but there is no explicit when-to-use, when-not-to-use, or reference to alternatives such as photos_update_album for modifying an existing album. Adequate but leaves routing 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 say destructiveHint=true; the description adds genuinely non-obvious behavior: refusal on non-empty albums, the force override, the guarantee that underlying photos are preserved, and the confirmed gate. It also discloses the save parameter's lack of observable effect, which is exactly the kind of quirk an agent cannot infer elsewhere.

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 verb and resource, then layers prerequisites, side effects, and the save caveat in five tight sentences with no filler. Each clause carries decision-relevant information.

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 destructiveHint already declared and no output schema, the description covers prerequisites, failure modes, side effects, and safe-invocation workflow. Nothing an agent needs to call this 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 description coverage is 100%, so the baseline is 3, but the description adds real semantic value on top: confirmed is framed as user acknowledgement, force as the non-empty-album override, and save is actively advised against ('leave it off unless asked'). This is more than the schema restates.

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 ('Delete a Proton Photos album') and immediately scopes the blast radius ('Never deletes your own photos; they stay in the timeline'), which distinguishes it from sibling tools like photos_remove_from_album and photos_update_album. An agent knows exactly what object is destroyed.

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 clear preconditions (confirmed=true), the force condition for non-empty albums, and a workflow instruction ('Show the user the album name and photo count first'). It does not explicitly name an alternative tool for the case where the user wants to remove the photos rather than the album, so it stops short of full routing guidance.

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

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

Goes well beyond the annotations: discloses atomic failure ('Fails if any item fails'), that 'remove' deletes the existing LOCAL file, and that confirmed=true is required for that path. The annotations only declare openWorldHint/destructiveHint, so this extra operational context is genuinely additive.

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

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

Dense and front-loaded: path requirement first, then conflict behavior, then failure/confirmation constraints. Every sentence carries information, though the run-on conflict sentence is somewhat packed.

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 it adequately covers accepted input forms, conflict semantics, atomicity, and the confirmation gate needed for the destructive-by-local-file option. Minor gap: it doesn't state what comes back on success (e.g., per-file results) or partial-failure reporting beyond the all-or-nothing note.

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 already 100%, so the baseline is 3, but the description adds real semantics the schema lacks: that timeline photos can share a filename, that only one copy survives under 'skip'/'remove', and that 'rename' preserves all copies.

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

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

States a specific verb+resource ('Download photos from your timeline to a local folder') and narrows scope with the required '/photos/<name>' path form. It also carves itself away from sibling operations like photos_upload/photos_list_timeline by describing the download direction and accepted path shape.

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

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

Explicitly says album paths are rejected and to use the /photos/ path instead, and it tells the agent when to pick 'rename' vs 'skip'/'remove' for filename conflicts. It lacks routing to sibling tools (e.g., upload), but the when/when-not guidance for this tool's own options is strong.

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

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

Annotations only declare readOnlyHint/idempotentHint, but the description goes far beyond: it discloses the return envelope, default limit, sort ordering (newest capture first, ties by nodeUid), the caveat that order collapses to nodeUid without loadDetails, and the important warning that each page is a fresh read so concurrent changes can shift items. That pagination-instability disclosure is exactly the kind of trait annotations cannot express.

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, then progressively layers return shape, ordering, and the mutation caveat — no sentence is filler. It is dense with parentheticals, though, which slightly hurts scannability for an agent parsing it quickly.

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 carries the full burden and does so: it names the response keys, item shape for both loadDetails modes, and the pagination contract. An agent has everything needed to call and interpret this tool without opening the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: it explains the interaction between loadDetails and captureTime availability, and that omitting loadDetails changes effective ordering to nodeUid. The only gap is that it restates the default limit already in the schema.

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

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

Opens with a specific verb+resource ('List the photos in an album'), which cleanly separates it from photos_list_albums, photos_list_timeline, and photos_create_album. It further disambiguates by pointing out that add/remove operations belong to the /photos/ path, routing the agent away from photos_add_to_album/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?

The final sentence explicitly routes mutation intent to a different tool family ('To add or remove photos use their /photos/ path'), which is genuine when-not guidance. However, it never states when to pick this over photos_list_timeline or how album-scoped listing relates to a global timeline listing.

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 useful context: the response shape and the '/albums/<name>' path convention. It does not mention pagination or ordering, which is a minor omission for a list operation.

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 compact sentences, front-loaded with the resource and scope, then the return shape and path format. No filler.

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

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

No output schema exists, and the description compensates by listing the fields in the returned objects plus the album path convention. Only pagination/ordering behavior is left unspecified, which is a small gap for this simple read 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 tool takes zero parameters, so there is nothing to disambiguate; baseline is 4. The description correctly indicates the operation is unfiltered (lists ALL albums).

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') and resource ('all Proton Photos albums') and even previews the returned fields. It separates albums from album photos implicitly, though it never names photos_list_album_photos as the sibling for a different resource.

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

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

No guidance on when to call this versus photos_list_timeline or photos_list_album_photos, and no stated preconditions (e.g. authentication). The agent must infer usage entirely from the name and the sibling 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavior beyond annotations: pagination stability caveat ('each page is a fresh read, so changes between pages can shift items'), default page size, ordering rules, and token-cost impact of loadDetails.

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, then efficiently packs return shape, pagination caveat, field variations, token cost, and an alternative. It is dense with parentheticals but every clause earns its place; minor run-on feel keeps it from a 5.

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?

No output schema exists, but the description fully explains the return shape, pagination behavior, field expansions, token tradeoff, and the relevant download alternative. Combined with annotations covering safety, an agent has everything needed 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 description coverage is 100%, so baseline is 3. The description adds meaningful details not in the schema: default limit 50, newest-first ordering with nodeUid tie-break, and loadDetails expanding items to include name, mediaType, creationTime, totalStorageSize at roughly 50% more tokens.

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

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

States a specific verb+resource: 'List photos in your full Proton Photos timeline.' This clearly distinguishes it from album-listing siblings by scope, and explicitly names photos_download as the tool for downloading.

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 clear context for when to use it (full timeline listing) and points to photos_download as an alternative for downloading. However, it does not explicitly contrast with photos_list_albums or photos_list_album_photos, leaving some inference to the agent.

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=true, so the description usefully narrows what is destroyed: the photo leaves the album but remains in the library/timeline. It also discloses a required confirmation gate tied to prior user approval. It does not cover error behavior or whether the album order is preserved.

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 short clauses, front-loaded with the action and its non-destructive scope, then the confirmation requirement. No filler or redundant restatement of the name.

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

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

With no output schema and only a single destructiveHint annotation, the description carries the needed safety context: scope of removal, library retention, and the approval gate. Adequate for a simple 3-parameter tool, though it omits any mention of failure modes or path-validation errors.

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

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

Schema description coverage is 100%, and the schema already documents both path formats and the confirmed=true condition with its exact semantics. The description restates the confirmation rule rather than adding new parameter detail, 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?

States a specific verb and resource (remove a photo from an album) and immediately scopes it: the photo is not deleted from the library and stays in the timeline. This clearly separates it from photos_delete_album and drive_delete, which an agent could otherwise confuse it with.

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 effectively states the context of use by contrasting removal-without-deletion with the destructive alternative, and it names the confirmed=true precondition tied to explicit user approval. It does not, however, explicitly name the sibling tool an agent should use instead when a true deletion is wanted.

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=false, so the description carries most of the burden. It adds the useful 'omit to leave unchanged' semantics and the at-least-one-required rule, but says nothing about permissions, whether the old cover is replaced, or error behavior on a bad albumPath.

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, zero filler, with the core action stated first and the constraint/cross-reference second. Every clause earns its place.

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

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

For a three-parameter mutation with no output schema and a minimal annotation set, the description covers the action, the required-input rule, and how to source a cover UID. The main remaining gap is lack of any note on permissions or failure modes.

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 all three parameters including their omit-to-leave-unchanged behavior. The description reinforces the cross-parameter constraint, which is genuinely additive, but adds no format or syntax detail beyond the schema. Baseline 3 applies.

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

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

The description opens with a specific verb and resource pair ('Rename an album or change its cover photo'), covering both operations the tool performs. It is clearly distinguishable from adjacent siblings like photos_add_to_album or 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?

It states the calling constraint explicitly ('At least one of name or coverPhotoUid is required') and routes the agent to photos_list_album_photos to obtain a valid cover nodeUid. It does not spell out when this tool should be preferred over other album-mutating siblings, but the required-parameter guidance is concrete.

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

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

Beyond the annotations, the description discloses important behavioral traits: non-media files are skipped and counted, folders are recursed but flattened so structure is not preserved, and duplicates never overwrite. These details materially affect how an agent should invoke and interpret the tool.

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

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

Three sentences, front-loaded with the primary action, followed by concise behavioral constraints. Every sentence adds distinct value, and there is no redundant restatement of the title or 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 two-parameter upload tool with rich input schema coverage, the description covers the key invocation behavior and side effects. It is slightly incomplete about return details beyond skippedItems and does not mention auth, size limits, or progress behavior, but there is no output schema requiring that elaboration.

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 would be 3. The description still adds meaning by clarifying that folder paths are recursed but flattened, and by emphasizing that duplicate handling never overwrites, which reinforces the conflictStrategy semantics beyond the enum 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 gives a specific verb and resource: upload local photo/video files into the Proton Photos library. It clearly distinguishes this from the sibling drive_upload by scoping the operation to Photos, and it names the accepted media types upfront.

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 makes the intended use clear: local photo or video files for Proton Photos. It also implies when not to use it by stating that non-photo/video files are skipped, though it does not explicitly route the agent to an alternative such as drive_upload.

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