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

Goes beyond the single destructiveHint annotation by disclosing what is destroyed (staged parts and staged data), what is guaranteed not to happen (nothing added to the drive), and the required scope (files:upload). The one destructiveHint=false is not contradicted because the effect is scoped to staged, not existing, content. It stops short of covering idempotency (aborting an already-aborted upload) or error 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?

Three sentences, front-loaded with the effect, then the trigger and the alternative, then the return and scope. 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?

An output schema exists and 'Returns success' aligns with it, so return values need no elaboration. Effect, trigger, alternative, and auth scope are all present; only edge cases like re-aborting or invalid upload_id are unaddressed.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and the description adds nothing about upload_id handling or the presence of limit/first_part. Baseline 3 applies when the schema carries parameter meaning.

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

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

States a specific verb (cancel/abort) and resource (upload created by prepare_upload), plus the concrete effect: stop accepting parts, delete staged data, nothing added to the drive. This clearly distinguishes it from completion/wait/get_upload_parts siblings.

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

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

Gives explicit triggers (user cancels, local file changed) and names the alternative for the contrasting case ('to continue an interrupted upload instead, use get_upload_parts'). An agent can route correctly without 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?

The single annotation (destructiveHint: true) only flags danger; the description adds substantive behavior beyond it — partial failure with per-item errors, dry_run validation with full rollback, and the fact that preview IDs from a dry run cannot be reused. It does not say whether trashed items are recoverable or what permissions are required, which is the remaining gap for a destructive 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?

Four sentences, front-loaded with what the tool does and followed by the sibling contrast and the two behavioral gotchas. A little space is spent repeating the dry_run/preview wording already present in the schema, but nothing is genuinely wasteful.

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 seven-parameter destructive batch tool, the description covers batch limits, per-item result shape, dry-run rollback, and idempotent replay semantics; return values are covered by the output schema. An agent has what it needs to invoke this correctly and safely.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by adding consequences the schema lacks: an idempotency_key replays the original entire result including failures, so a new key is needed to retry failed items. It does partly restate schema text for dry_run and preview IDs rather than extending it.

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

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

The first sentence names four specific verbs (move, copy, trash, restore), the resource (nodes), and the batch limit (100) with per-item results. It then explicitly distinguishes itself from the four single-operation siblings by naming them.

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 states the selection rule directly: use this tool when each item should succeed or fail independently, and use move_nodes, copy_nodes, trash_nodes, or restore_nodes when all-or-nothing semantics are wanted. That is an explicit alternative plus the condition that selects 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?

readOnlyHint=true already tells the agent this is a safe read. Beyond that, the description adds the fixed conversation scope and the oldest-first ordering, which are useful traits, but says nothing about page size behavior or what happens when the cursor is omitted.

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 sentence, front-loaded with the verb and scope, with the cursor caveat trailing. Nothing is redundant, though the quoted conversation name plus ordering plus cursor in a single clause is slightly dense.

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?

An output schema exists, so return values need no explanation, and the tool is a simple three-optional-parameter read. The description covers scope, ordering and one cursor, leaving only forward pagination and default sizing to the schema.

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

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

Schema description coverage is 100%, so limit, after_id and before_id are already documented with semantics and mutual exclusivity. The description only echoes before_id as a cursor and adds no syntax or format detail beyond the schema, making the baseline 3 appropriate.

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

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

The description names a specific verb (List) and resource (messages) scoped to a single conversation, '我的设备', and states ordering (oldest first). That distinguishes it from the write-side sibling chat_send, though it never names that sibling outright.

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 mentions the optional before_id cursor, which implies paginated backward traversal, but gives no explicit when-to-use or when-not guidance and does not explain the after_id alternative for forward paging that the schema exposes.

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?

Only destructiveHint=false is supplied, so the description adds some value by stating the 'already saved' constraint, which implies no server-side upload occurs. It says nothing about authentication/permission requirements, rate/duplicate behavior despite an idempotency_key being present, what happens if both or neither payload is supplied, or that the message lands in a persistent chat.

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 with the destination and payload types front-loaded and the node_id precondition following immediately. Every clause carries information; 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?

The tool is simple (3 optional parameters, mutual exclusivity documented in schema, output schema present so return values need not be explained), and the description covers payload options and the key precondition. Minor gaps remain around idempotency behavior and what occurs when neither text nor node_id is provided.

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 genuinely adds meaning beyond the schema by constraining node_id to nodes already saved by this account — a real invocation precondition not captured in the schema text. It does not clarify the idempotency_key semantics or the mutual exclusivity beyond what the schema states.

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 (send) and two precise payload types (text message or saved file node) and pins the destination to the account's file-transfer conversation ('我的设备'). That scope makes it unmistakably distinct from siblings like write_text_file, create_share, or chat_list.

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

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

The description establishes a clear usage context (sending to your own device conversation) and a precondition for node_id ('must be a node already saved by this account'), which effectively rules out using this tool to upload new content. It gives no explicit when-not guidance or naming of alternatives, so it falls short of a 5.

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

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

Annotations provide only destructiveHint=false, and the description carries the rest: the operation is asynchronous and returns a job, images are stored alongside the Markdown file, duplicate URLs return the existing clipping unless 'force' is used, folder-scoped credentials are rejected, files:upload is required, and idempotency is supported. This goes well beyond the annotation's minimal safety hint.

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

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

The description is three tight sentences that front-load the action and result, then the async polling path, then constraints. Parentheticals carry real information (images downloaded, result_node_id) rather than padding.

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

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

For an asynchronous job-creating tool with a three-parameter schema, the description covers the return path, the dedupe case, permission requirements, and credential limitations. Even though an output schema exists, the inline explanation of result_node_id and get_job polling is enough for an agent to call and follow up 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?

At 67% schema coverage, url and force are already documented in the schema, but the description adds the deduplication behavior that makes 'force' meaningful and notes idempotency support, which partially clarifies the undocumented idempotency_key parameter. It still doesn't explain the expected format or usage of idempotency_key directly.

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: 'Save a web page's main article as a Markdown file ... into the user's clippings folder'. The stated output (.md plus downloaded images, background job) is distinct enough from siblings like fetch_url that an agent can choose without opening a 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?

Clear context for use (clipping an article page), plus explicit prerequisites ('Requires files:upload') and exclusions ('Not available to credentials limited to a folder'). It also routes follow-up work to siblings (get_job, read_text_file). It never names a competing tool such as fetch_url as the alternative for raw or non-article fetches, so 'when-not' guidance is implied rather than stated.

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 load and does add real value by disclosing that completion kicks off hashing, verification, deduplication, and commit on the server. It stops short of saying whether the call returns immediately or blocks, whether it is idempotent on repeat calls, or what happens if parts are missing.

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 front-loaded sentence with no filler; the action leads and the consequences follow. Nothing could be removed without losing 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?

An output schema exists, so return shapes need not be explained, and the description adequately conveys the core behavior for a three-parameter tool. The remaining gap is flow-level: an agent is not told whether this is an asynchronous trigger that requires polling via wait_upload or get_upload_status.

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 upload_id, first_part, and limit are already documented in the schema. The description adds no parameter meaning at all, which is the baseline case when the schema does the work, though it also doesn't clarify why limit and first_part appear on a completion call.

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: 'Declare a direct upload complete' and enumerates the server-side work started (hashing, verification, deduplication, commit). This is far more specific than a bare name restatement and implicitly separates it from prepare_upload, abort_upload, and wait_upload, but it never names or explicitly contrasts those siblings.

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

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

Usage is only implied: the phrase 'declare a direct upload complete' signals this is the final step of a direct-upload flow. There is no explicit statement of prerequisites (all parts uploaded), when not to use it, or whether to follow with wait_upload versus get_upload_status.

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

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

Annotations only declare destructiveHint=false, but the description adds substantial behavior: content deduplication with no re-upload, quota accounting and the QUOTA_EXCEEDED failure mode, all-or-nothing atomicity, and the files:write scope requirement. The idempotency guidance for safe retries is exactly the kind of context annotations do not 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?

The description is dense but every sentence carries distinct information: scope, destination, dedup/quota, atomicity, alternative tool, auth, idempotency. The most decision-relevant facts (what it copies, where, the batch_nodes alternative) come first.

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?

An output schema exists, so return values need not be spelled out; the description nonetheless notes it returns the new nodes. Quota, atomicity, permission scope, and retry safety are all covered, leaving nothing an agent needs in order 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 still adds value by explaining the target_folder_id/target_path mutual fallback to root and framing idempotency_key as the mechanism for safe retries rather than just a 'stable retry key'. It does not add format or syntax detail beyond that.

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

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

The description opens with a specific verb and resource ('Copy one or more files or folders (folders recursively)') and immediately bounds the destination semantics. It is clearly distinguishable from siblings such as move_nodes and batch_nodes.

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 both the when-to-use condition and the alternative: use batch_nodes for per-item results or a dry-run preview. It also resolves the destination ambiguity by saying to omit both target parameters for the root.

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 lone destructiveHint=false annotation, the description discloses real behavioral traits: the operation is atomic, existing directories are reused rather than replaced, and idempotency keys are persisted. It does not cover what happens if the path collides with a file or how partial failures surface, which keeps it from a 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?

Two tightly packed sentences with zero filler, and the core atomicity/reuse constraint is front-loaded before the idempotency note.

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 only two parameters, full schema coverage, and an output schema to describe results, the description covers what an agent needs to invoke it correctly. Missing are edge-case behavior (path already exists as a file, error semantics) that a mutation-style tool would ideally state.

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

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

Schema coverage is 100% and both parameters are documented in-schema, including the 128-byte limit on the key, so the baseline is 3. The description only restates the path/reuse behavior and adds no new meaning about the idempotency key beyond what the schema already says.

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 ('create missing parent directories') plus the reuse semantics, so the operation is unambiguous. It does not, however, distinguish itself from the sibling create_folder, which an agent must resolve on its own.

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 only implied: 'missing parent directories' and 'reuse existing directories' suggest this is the right call for nested absolute paths created in one shot. There is no explicit when-to-use versus create_folder, no stated preconditions, and no exclusion 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 supply only destructiveHint=false, so the description carries the real burden and does: anonymous uploaders cannot see folder contents, uploads consume this account's quota, shares:write scope is required, idempotency is supported, and the deadline is soft ("uploads started before it may finish"). Those are exactly the non-obvious behaviors an agent needs before calling.

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 dense sentences with the core capability and access model front-loaded, followed by optional features, then operational constraints (quota, auth, idempotency). No sentence restates the name or wastes words.

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

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

For a 12-parameter mutation tool, the definition covers access model, quota impact, auth scope, idempotency, and expiry semantics; an output schema exists so return values need no explanation. 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 67%, and the description adds meaning on top: it groups password, deadline, uploader name, per-uploader subfolders, and size/count limits as optional constraints, and states the quota implication of the limit parameters. Undocumented fields like idempotency_key and folder_id versus path are only lightly covered, keeping it below 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?

Opens with a specific verb and resource: "Create a file request link for a folder," and immediately defines the resulting artifact's semantics (anonymous upload-only, contents invisible). That distinguishes it from create_link, create_share, and list_file_requests without the agent needing to open a 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 conveys the scenario clearly (collect files from people without accounts) but never names a sibling alternative or an explicit when-not condition, e.g. versus create_link or create_share. Usage is implied by the capability description rather than stated as 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?

Annotations only declare destructiveHint=false, so the description carries most of the burden and does well: it discloses name-collision behavior (auto-numbering rather than failure), that the returned node reflects the actual name used, the files:write permission requirement, and idempotency_key's retry-safety role. It stops short of describing failure modes beyond collisions, but covers the 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 tight sentences, front-loaded with the core action and parent scoping, then collision semantics, then the alternative sibling, then prerequisites. Every sentence carries distinct 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?

With an output schema present, return format needn't be explained, yet the description still flags that the returned node shows the resolved name. Prerequisites, collision handling, root default, and the sibling alternative are all covered for a 4-param mutation 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; the description adds meaning by framing parent_id vs parent_path as mutually exclusive alternatives with a root default, and by explaining why idempotency_key matters (safe retries) rather than just that it exists.

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 one new folder') plus its scope ('inside parent_id or parent_path'). It explicitly distinguishes itself from the sibling create_directories, so an agent can pick correctly 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 concrete routing rules: omit both parent args for root, and use create_directories instead when creating a whole nested path. It names the alternative 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?

With only destructiveHint=false in the annotations, the description carries most of the burden and does well: it discloses public exposure, access logging, a per-day cap, the required shares:write scope, and that a call may return an already-existing link rather than create a new one. It stops short of explaining link lifetime/revocation or how the daily cap behaves when hit.

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

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

Front-loaded with the core action and outcome in the first clause, then permissions and idempotency. The semicolon-heavy packing is dense but every fragment (embedding, logging, cap, scope) carries information an agent needs.

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?

An output schema exists, so return values need not be described. However, for a tool whose main ambiguity is target selection (path vs node_id) and whose behavior is permanent public exposure, the description should say which parameter to use and how the link can later be revoked via revoke_link.

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 0% across three parameters, so the description must compensate and largely does not. It mentions idempotency (mapping loosely to idempotency_key) but says nothing about path versus node_id, does not indicate whether they are alternatives or which one to supply, and all three are optional, leaving the agent unsure how to identify the target file.

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 return existing) a permanent public direct URL for one file, with the web page/Markdown embedding use case made concrete. It is clearly distinguishable from create_share, clip_url, and create_file_request, though it never names those siblings explicitly.

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

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

Usage context is implied through examples ('usable in web pages and Markdown; images can be embedded directly'), which tells the agent what kind of link this is for. There is no explicit when-to-use-this-instead-of-create_share or create_file_request guidance, and no stated prerequisites beyond the permission scope.

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 single destructiveHint=false annotation, the description discloses the required auth scope and idempotency support, both of which materially affect how an agent should call it. It stops short of stating that omitting a password yields an openly public URL, or that expiry must be a future timestamp.

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 action and its key options, with the operational constraints appended. No wasted words.

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

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

An output schema exists, so return values need no explanation, and auth plus idempotency are covered. The remaining gap is the path/node_id ambiguity and the public-by-default implication, which matter for correct invocation.

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

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

Schema description coverage is only 17% (just allow_upload), so the description must compensate. It only glosses password and expiry in passing and says nothing about path vs node_id (both optional per schema, which is itself ambiguous) or the format of expires_at/idempotency_key.

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 public share URL') plus its two main optional dimensions (password, future expiry). However, it does not distinguish this from the sibling create_link, which an agent could plausibly confuse with a share-link creation tool.

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

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

It gives a prerequisite ('Requires shares:write') but offers no when-to-use/when-not guidance and no pointer to alternatives such as create_link or list_shares. Usage context is only implied by the word 'public'.

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, and the description adds substantial context beyond that: extraction runs in the background, existing files are never overwritten and clashes get a numeric suffix, and encrypted, link and unsafe-path entries are skipped. The non-destructive claim is consistent with the annotation and is actually explained.

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 tight sentences, each carrying distinct information: what it does, overwrite policy, async job flow, skip rules, and permission requirement. The core action and the polling instruction are front-loaded, and there is no filler.

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

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

For an asynchronous extraction tool with an output schema, the description covers everything an agent needs: the async lifecycle, where the result lands, collision behavior, skipped entry classes, and the auth requirement. Return-value details are correctly left to the output schema.

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

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

Schema description coverage is 100%, so each of the six parameters is already documented. The description adds framing that paths can be a subset and that the output folder is named after the archive (implying the parent_id default), but offers no additional syntax or format detail beyond the schema.

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

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

States a specific verb (extract) and resource (archive), plus scope options (all of it, or selected paths) and the output shape (a new folder named after it). This clearly separates it from siblings like list_archive or prepare_download, which inspect or fetch rather than unpack.

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 concrete follow-up routing: it returns a job, so poll get_job with wait=true until done, then read result_node_id. It also states the required permission (files:upload). It does not explicitly say when to prefer this over inspecting the archive first with list_archive, so it falls short of full alternative coverage.

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 the behavioral load and does so: it discloses asynchrony (returns a job, not a file), server-side fetching, rejection of private/internal addresses, non-idempotency with a retry procedure, and the files:upload scope requirement. These are exactly the traits an agent would otherwise get wrong.

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 behavior, then layers the follow-up workflow, safety constraint, idempotency warning, and auth requirement in separate short clauses. No sentence is redundant with another or with 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?

Even though an output schema exists, the description usefully explains the async job handoff (job → get_job → result_node_id), which is workflow rather than return-value detail. For a 3-parameter non-idempotent network-fetching mutation, 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 description coverage is 100%, so url, parent_id, and parent_path are already documented including the root/credential-directory default. The description adds no additional parameter semantics (no format, encoding, or parent_id-vs-parent_path precedence), so the baseline of 3 applies.

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

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

"the Gopan server fetches an http(s) link into a folder in the background, so the bytes never pass through the agent" states a concrete verb (fetch), resource (http/https link into a folder), and the defining property (server-side/offline rather than agent-mediated) that separates it from agent-side download paths. An agent can tell what this does 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 an explicit follow-up workflow ("poll get_job (wait=true) until status is done") and an explicit precondition before retrying ("check list_jobs before retrying"), plus the required scope. It stops short of naming a sibling alternative for the alternate case (e.g. when clip_url or prepare_download is the better choice), so not a full when/when-not treatment.

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

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

The description adds useful context beyond readOnlyHint=true: it says the operation is cheap, requires files:read, and explains folder-specific fields including the stats_stale recalculation state. It does not describe pagination or error behavior, but those are not central for this simple metadata lookup.

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

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

The description is front-loaded with the core operation and then supplies the return fields, folder caveat, alternatives, and permission requirement in compact order. The field list is dense but each item helps the agent recognize the metadata response.

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 metadata lookup with an output schema, this covers the necessary selection guidance, permission requirement, and sibling alternatives. The output schema carries return structure, and the description still surfaces the most important fields and a folder-specific staleness caveat.

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 path and node_id are already documented in the input schema. The description reinforces that either identifier can be used but adds no syntax or format details beyond the schema.

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

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

The description uses a specific verb and resource ('Get metadata for one file or folder'), states the identifying inputs (node_id or absolute path), and enumerates the returned fields. It clearly distinguishes itself from content-reading and download siblings.

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

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

It explicitly routes the agent to alternatives: read_text_file or read_document_text for contents, and prepare_download for downloading. This leaves little ambiguity about when to use get_file_info versus its 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 only declare readOnlyHint=true, so the description earns credit for disclosing the blocking behavior and the concrete 25-second cap on wait=true, which an agent must know to avoid appearing hung. It stops short of saying what is returned if the job has not finished within that window, which is the one behavioral detail still missing.

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, no filler, with the core purpose stated first and the blocking caveat second. Every clause carries information an agent needs.

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 read tool with full schema coverage and an output schema, this covers what is needed to call it correctly. The only shortfall is the unstated post-timeout behavior, which matters for interpreting a returned in-progress status.

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

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

Schema coverage is 100%, with both job_id and wait already documented in the schema, including the 'up to 25 seconds' phrasing. The description restates the wait semantics rather than adding new meaning such as default value or what wait=false implies. 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 ('Get the status and progress of a background job') and enumerates the job kinds it covers (offline download, archive extraction). An agent can tell it apart from mutation siblings, though it never names list_jobs, the closest read 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?

Usage is only implied: the schema notes job_id comes from fetch_url or extract_archive, and the description explains the wait flag. There is no explicit guidance on when to poll with this tool versus listing jobs with list_jobs, nor when to prefer wait=true over repeated calls.

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 the rest and does so well: it discloses what is returned (uploaded_parts), the batch ceiling of 100 per call, that URLs are presigned and can expire, that file bytes flow through the caller's own HTTP client rather than MCP, and the required files:upload scope. That is exactly the behavioral context an agent needs before calling.

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

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

Four sentences, no filler, and the identity/scope sentence is front-loaded before the usage triggers and the auth requirement. Every clause adds information an agent would otherwise have to infer.

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?

An output schema exists, so return values needn't be spelled out, and the description still names the key field; the auth requirement and the out-of-band byte transfer are both covered. The only minor gap is no guidance on how to proceed when the part list is incomplete beyond calling again, though the resume wording largely implies 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 real meaning by framing limit and first_part as a sliding batch window ('a range of parts (first_part, up to 100 per call)') and by explaining why you would request a later range — expired or already-consumed URLs. That goes beyond the per-field 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 pair and resource — report received parts and issue fresh presigned PUT URLs — and anchors it to the upload created by prepare_upload. This clearly separates it from get_upload_status, complete_upload, and prepare_upload without needing to open a 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 three concrete when-to-use triggers: resuming an interrupted upload, fetching URLs beyond the first batch, and replacing expired URLs. It does not name sibling alternatives or state when-not-to-use (e.g. when to prefer get_upload_status or wait_upload instead), which keeps 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 only supply destructiveHint=false, so the description carries most of the burden and does it well: it discloses the non-blocking single-shot semantics, the full status vocabulary including terminal states (ready/failed/aborted), and the files:upload scope requirement. It does not discuss error behavior or how long statuses remain queryable.

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 core behavior comes first, the status enumeration second, and the sibling routing last. It is slightly packed into one long sentence run, but no sentence 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?

An output schema exists, so return values need not be explained, and the description covers the essentials: non-blocking behavior, state machine, permission requirement, and the alternative tool. Minor gaps around error/expiry behavior remain.

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

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

Schema description coverage is 100%, so the schema already documents upload_id, limit and first_part, making 3 the baseline. The description adds no parameter-level meaning, and notably does not explain why a status check exposes part-URL parameters, leaving that ambiguity entirely to 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 ("Return the current status of an upload") and immediately pins down the scope with "once, without waiting," then enumerates the exact status values an agent will see. This clearly separates it from wait_upload, which is named explicitly.

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

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

Gives an explicit routing rule: poll here for a single snapshot, but if you need to wait for completion after complete_upload, use wait_upload instead of calling this repeatedly. Both the when and the named alternative are present.

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

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

Annotations only declare readOnlyHint=true; the description adds ordering (newest first), the pagination mechanism (before_id cursor), the fact that undo is not exposed via the API, and the required scope ("Requires audit:read"). The auth requirement and the undo limitation are exactly the kind of behavioral context annotations cannot 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?

Front-loaded with the core purpose, then filters, then pagination, then the sibling disambiguation and auth note — a sound ordering. The long parenthetical source list and the compressed "who did what to which file and where" phrasing make it dense, but every clause carries 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?

An output schema exists, so return values need not be described. For a six-parameter read-only listing tool, the description covers scope, ordering, filtering model, pagination, an exclusion, and the auth scope — 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%, so the schema already documents every parameter including the actor enum values, the 1-200 limit range, RFC 3339 for since, and the before_id cursor semantics. The description only restates the filter dimensions (source kind, action, time, node history) at a higher level without adding format or combination rules. 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 recent changes to the drive") plus scope ("from every source (web, Android app, WebDAV, agents, file requests, background jobs)") and ordering ("newest first: who did what to which file and where"). It also names the sibling it is not (list_audit), so an agent can distinguish it 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?

Explicitly routes the agent to the alternative: "For the log of MCP tool calls themselves, use list_audit." It also states a boundary the agent would otherwise have to discover at runtime — "Undo is only available to the user in the app" — which prevents a futile undo attempt.

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?

readOnlyHint=true already declares this is a safe read, and the description adds genuinely new behavioral context: contents are read server-side without downloading, and a PENDING status means an in-progress read that should be retried. It stops short of saying whether results are truncated or how a PENDING response is shaped, so with annotations already covering safety the added value is moderate rather than rich.

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 operation and its key constraint front-loaded before the async PENDING caveat. Every clause carries information an agent needs.

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 four-parameter read tool with readOnlyHint and a present output schema, the description covers purpose, scope, format set, and the one non-obvious behavior (asynchronous PENDING). Remaining gaps, cursor semantics and the path/node_id precedence, are modest but real.

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 75% and the schema itself documents dir, path, and node_id, including format examples, so the description contributes little parameter-level detail. "one directory at a time" loosely motivates dir and cursor paging, but cursor remains undocumented in both places and the path-vs-node_id choice is not resolved.

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 ("List what is inside an archive file") and enumerates supported formats plus the non-downloading scope, so the operation is unambiguous. It implicitly separates itself from extraction siblings by stressing "without downloading it," but it never names extract_archive as the alternative, so sibling routing is left to inference.

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?

"one directory at a time" tells the agent to navigate level by level rather than expect a full recursive listing, and the PENDING note tells it to retry instead of treating the response as an error. What is missing is explicit guidance on choosing this over extract_archive or list_files, and on how to advance the cursor.

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, so safety is covered; the description adds genuine context beyond that: secrets and tokens are never included in results, and directory-restricted credentials see only their own events. It does not discuss pagination behavior, though the before_id parameter hints at it in the 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?

Two sentences, front-loaded with what is returned, then the credential-scoping caveat, then the sibling redirect. Every clause carries information; nothing is redundant.

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

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

For a two-parameter read tool with an output schema and readOnlyHint, the description covers scope, data exclusions, and an alternative. Only the paging workflow is left implicit in the schema rather than stated.

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% for both parameters (limit default 50/max 200, before_id paging), so the schema carries this burden. The description adds no parameter-level meaning, which meets baseline 3 without standing out.

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 ('Read the log of MCP tool calls') and enumerates the exact fields returned: tool name, credential, targets, outcome. It is clearly distinguishable from the sibling list_activity, which it explicitly names and contrasts.

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 (list_activity) and the condition that selects it: file-change history from every source, versus MCP tool-call history for this account. An agent can route between the two without opening either schema.

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?

readOnlyHint=true already declares the safety profile, so the description's job is to add context, which it does by naming the required permission scope (shares:read) and disclosing that rows carry received file counts and cover only active requests. It does not say whether revoked or expired requests are excluded entirely or simply absent, which is the one remaining ambiguity.

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 no filler: the first identifies the resource and what its rows contain, and the second front-loads the authorization requirement. Nothing repeats the title or the annotations.

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

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

For a zero-parameter read with an output schema already describing the return shape, the description covers the only things an agent still needs: what a file request is and what scope it must hold. No behavioral or structural gap remains that would change how the call is made.

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 and the schema is a closed empty object, so there is nothing for the description to disambiguate. It does not misuse the space by inventing filters that do not exist, which would be a worse failure than saying nothing.

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 pairs a specific verb ("List") with a specific resource ("file request links") and then defines that resource as "anonymous upload links into a folder." That gloss is what lets an agent separate it from list_links or list_shares without opening a 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 word "active" implies the results are filtered to non-revoked requests, and the required scope is stated, which gives an agent enough context to decide it is the right listing call. However, there is no explicit when-to-use rule and no pointer telling the agent to prefer list_links or create_file_request under specific conditions.

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 annotation by disclosing the 200-item page cap, the default sort order, the non-recursive behavior, the requirement for files:read, and how next_cursor feeds back into cursor. It does not cover error behavior for a bad parent_id/path, which keeps it from the top score given annotations already carry the safety profile.

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 core action, then addressing identifiers, response shape/paging, and the sibling boundary. Every clause carries operative information for a caller.

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 paginated list tool with a full output schema and annotations, the definition covers scope, paging, sorting, identifier options, and permissions without redundancy. 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 description coverage is 100%, so the baseline is 3. The description adds real meaning: 'name' is the default order, parent_id and path are mutually exclusive substitutes, and cursor should be the previous call's next_cursor. The desc parameter's interaction with order is left implicit.

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 direct children ... of one folder') with scope ('does not recurse') and paging limits. It names the sibling tools that cover the non-recursive case (search_files, search_file_contents), so an agent can distinguish it from them 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?

Explicit routing guidance: omit parent_id and path for root, use path instead of parent_id as an alternative, and use search_files or search_file_contents when recursion or cross-drive lookup is needed. This covers when-to-use, when-not-to-use and the alternatives in a single sentence.

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, so safety is covered. The description adds genuinely useful context beyond that: the job categories covered and the 'newest first' ordering. It says nothing about whether the list is paginated via cursor or how far back it reaches, which matters for a listing 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?

One sentence, front-loaded with the verb and resource, with the clarifying examples and ordering kept as parenthetical. No filler or repetition 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?

An output schema exists, so return-value detail is not required. However, the undocumented cursor parameter and the absence of any routing versus get_job leave the definition thin for a paginated listing tool in a large sibling set.

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 50%: active_only is documented in the schema, while cursor is undocumented in both places. The description's 'newest first' hints at ordering but gives no guidance on cursor-based paging or what active_only changes in ordering/result set, so it compensates only partially for the gap.

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 ('List this account's background jobs') and clarifies scope with examples (offline downloads, archive extractions) plus ordering ('newest first'). It does not distinguish itself from the sibling get_job, which fetches a single job, so it stops short of full sibling differentiation.

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 only implied by the word 'List' – an agent can infer this is for browsing job history rather than fetching one job. There is no explicit statement of when to use this vs get_job, no mention of when to prefer waiting on a job, and no 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 readOnlyHint=true; the description adds meaningful behavior beyond that: results are active-only, ordered newest first, include access counts, and are cursor-paginated. It also discloses the required shares:read scope, which annotations do not cover.

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?

A single front-loaded sentence covering scope, ordering, pagination, and the permission requirement, with no redundant or filler wording.

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

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

With an output schema present, return values needn't be explained, and the description still notes access counts and ordering. The permission requirement and pagination are covered; only the lack of routing guidance to sibling listing tools leaves 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 0% for the single 'cursor' parameter, but the description compensates by naming it as a pagination cursor ('with cursor pagination'), which is the key semantic an agent needs. It stops short of stating opacity, expiry, or how to obtain the next cursor.

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

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

The description states a specific verb and resource ('List active direct URLs') plus scope details (active only, newest first). An agent can distinguish this from list_shares or list_files by the 'direct URLs' framing, though it never names those siblings explicitly.

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

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

There is no when-to-use guidance and no mention of alternatives such as list_shares or list_files for broader listings. The only contextual note is the 'Requires shares:read' permission, which is a prerequisite rather than usage guidance.

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

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

readOnlyHint=true already establishes this is a safe read, so the description's real contribution is the filtering semantics: only ACTIVE shares, only those OWNED by this account, and only within the credential directory. That tells the agent what will not appear in results, which is the main behavioral risk here. It stops short of covering ordering, pagination, or how expired/revoked shares are treated.

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 sentence, front-loaded with the verb and resource, with each qualifier carrying distinct meaning (active status, ownership, directory boundary). Nothing is repeated from the name or title and nothing is padding.

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

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

This is a low-complexity, zero-parameter read tool with an output schema, so the description does not need to explain return values. The scope qualifiers cover the important ambiguity, though it does not clarify whether shares owned by others but visible to this account are excluded, nor whether only unexpired shares qualify as "active".

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 and there is no parameter meaning for the description to supply. Its scope phrases instead describe implicit filters baked into the call, which is a mild bonus rather than a requirement.

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 ("List active shares") and narrows scope with two qualifiers: owned by this account and within the credential directory. This is enough to separate it from list_links and list_file_requests without opening a schema, though it never names those siblings to sharpen the contrast.

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 only implied: an agent can infer this is the read path where create_share and revoke_share are the write paths. There is no explicit when-to-use or when-not-to-use statement, and no mention of how to enumerate links versus shares if the agent is unsure which collection a resource lives in.

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 establish readOnlyHint=true, so the safety profile is covered; the description adds real behavior beyond that by disclosing that results include deletion times and that paging is cursor-based. The ID-reuse note for restore_nodes/batch_nodes is actionable operational context not present in the annotations.

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

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

Two short sentences with zero filler; the resource and its key attributes are front-loaded and the follow-up action is placed second. Every clause carries information an agent would otherwise have to infer.

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-required-parameter, read-only listing tool with an output schema and a fully documented cursor, the description supplies everything needed: what is listed, what metadata comes back, how paging works, and what to do with the results. No meaningful gap remains.

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 single parameter is fully documented in the schema ('cursor from the preceding page'), so the description's mention of 'cursor pagination' only echoes it. No additional semantics such as page size, ordering, or cursor expiry are added, which is the expected baseline at 100% coverage.

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

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

States a specific verb and resource ('List recoverable trash') plus the distinguishing scope detail that this is trashed-but-restorable content, which separates it from list_files and from the mutating trash_nodes/restore_nodes siblings. An agent can pick 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 forward routing: the returned IDs feed restore_nodes or batch_nodes, which tells the agent this is the discovery step before a restore. It stops short of an explicit exclusion (e.g. 'use list_files for active items'), so it is strong context rather than full when/when-not guidance.

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

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

Annotations only supply destructiveHint=false, but the description adds substantial context beyond that: all-or-nothing semantics, the two specific failure modes (NAME_CONFLICT, CYCLIC_MOVE) and their meanings, the required files:write scope, and the retry-safety purpose of idempotency_key. Nothing here contradicts the non-destructive hint, since a move relocates rather than deletes.

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 action and destination resolution, then atomicity, then the sibling escape hatch, then permissions. Every clause carries operational information; nothing is repeated from 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?

Covers destination selection, atomicity, failure modes, permissions, retry safety, and even briefly notes the return ("Returns the moved nodes") despite an output schema being present. For a four-parameter mutation tool this is fully sufficient to invoke correctly.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine meaning beyond the schema by explaining the either/or relationship between target_folder_id and target_path and the root default when both are omitted. It does not add format detail for the idempotency key beyond what the schema already states.

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 one or more files or folders into a destination folder") and implicitly distinguishes itself from copy_nodes and the broader batch_nodes by describing a single atomic move operation. An agent can identify the correct 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?

Gives explicit destination selection rules ("target_folder_id or target_path; omit both for the root") and names the alternative plus the condition that selects it: "For per-item results or a dry-run preview, use batch_nodes." It also states when to pass idempotency_key, leaving no inference required.

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 readOnlyHint annotation already tells the agent this is a safe, non-mutating operation, so the description gets credit mainly for the two traits it adds: the URL is "short-lived" and the ZIP ticket is "restricted". However, neither is quantified — no expiry window, no explanation of what the restriction enforces or whether the ticket is tied to the caller — and nothing says whether repeated calls are needed per file.

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?

A single well-formed sentence with the primary outcome ("short-lived direct GET URL") front-loaded and the alternate mode following immediately. There is no filler, hedging, 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?

An output schema exists, so return-value explanation is not required, and the readOnlyHint covers safety. What remains unaddressed is meaningful for a tool with zero required parameters: whether an empty call is valid, which of paths/node_id/node_ids wins if several are passed, and how long the URL or ticket lasts before the caller must re-invoke.

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 field-level docs already explain that "paths" replaces node IDs, that "node_id" is a single UUID, and that "node_ids" is for batches. The description reinforces the one-file versus multiple-node distinction but adds no format, precedence, or mutual-exclusivity rules beyond what the schema states, so the baseline of 3 applies.

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

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

The description gives a specific verb ("Create") and two concrete resources — a "short-lived direct GET URL" for one file versus a "restricted ZIP ticket" for folders and multiple nodes — so an agent knows exactly what the tool produces. It distinguishes the single-file and batch modes internally, but never names a sibling (e.g. prepare_upload or read_text_file) that it should be preferred over, which keeps it 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?

Usage is only implied: the two modes hint that a single file gets a direct URL while folders/multiple nodes get a ZIP ticket, letting the agent infer which inputs map to which behavior. There is no explicit when-to-use or when-not-to-use guidance, no mention of an alternative tool for streaming or text extraction, and no statement about what happens if no path or node is supplied.

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

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

The description adds meaningful behavior beyond the annotations: this tool creates an upload target, does not transmit file bytes itself, and SHA-256 can enable instant upload. It does not contradict destructiveHint=false. It still omits operational details such as upload expiry, auth requirements, or lifecycle expectations, so a 4 is appropriate.

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

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

Two short sentences with no wasted wording. The core action is front-loaded, followed by the critical operational note about SHA-256 and external byte transmission.

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?

An output schema exists, so return values need not be explained. The description captures the key non-obvious behavior that this tool prepares but does not perform the upload. For a complex multi-step upload workflow, however, it does not explain finalization with complete_upload, abort behavior, or multipart coordination.

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 parameters are fully documented in the schema. The description repeats the SHA-256 instant-upload behavior already stated in the schema and adds no further parameter guidance. 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?

The description states a specific verb and resource: 'Create a direct upload target.' It also clarifies that this tool only prepares the upload rather than sending bytes. It does not explicitly distinguish itself from sibling tools like complete_upload or get_upload_parts, 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?

The description gives an important usage constraint: the agent must send bytes with another HTTP-capable tool. It also mentions the optional SHA-256 shortcut. However, it does not say when to choose this over alternatives, nor does it explain the required follow-up flow with complete_upload or related tools.

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

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

readOnlyHint=true already declares the safe-read profile, and the description adds real value beyond it: extraction happens server-side without downloading the file, output is chunked, and continuation is expected. It does not describe error behavior (e.g., unsupported file type) or how node_id versus path resolution failures surface, but the output schema covers return 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?

Three short sentences, front-loaded with the capability, then the continuation protocol, then the alternative. Every sentence carries distinct information with no padding.

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

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

With an output schema present and readOnlyHint supplied, the description only needs to cover capability, chunking and routing — all present. The lingering gap is the 'next_offset' versus 'offset' inconsistency and no note on supported/max file size or how the file is identified, though the schema handles identification.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does add chunking semantics that corroborate max_chars (up to 50000 characters), but it refers to 'next_offset' while the actual schema parameter is named 'offset' — a naming mismatch that could mislead an agent trying to continue a read.

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 ('Read the extracted text of a PDF, Office or text file') plus the chunking scope, and explicitly distinguishes itself from the read_text_file sibling. 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?

Names the alternative and the selecting condition clearly ('For plain-text and code files where the exact bytes matter, prefer read_text_file'), and instructs continuation via next_offset. It stops short of covering other plausible alternatives in the sibling set (search_file_contents, prepare_download, view_image), so routing is clear for the main case but not exhaustive.

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 readOnlyHint=true: discloses the 64 KiB per-call ceiling, byte-offset paging so the agent knows a truncated read is expected rather than an error, that binary content is never loaded into context, and the required files:download permission. With an output schema present, that is the full behavioral picture the annotations do not 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?

Three dense sentences with no filler: capability and format scope first, paging and limit second, sibling routing and auth last. Every clause carries information the agent needs.

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

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

For a read tool with four parameters, full schema coverage, an output schema, and a readOnly annotation, nothing material is missing. The description covers format eligibility, size limits, continuation, exclusions, and sibling alternatives, leaving only the path-vs-node_id choice to the schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: offset is a byte offset and advancing it is the paging mechanism, and the 64 KiB figure ties max_bytes to a hard cap. It does not resolve the ambiguity between path and node_id, which the schema only gestures at.

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 ("Read raw UTF-8 text from a plain-text or code file"), enumerates the supported file types, and explicitly distinguishes itself from read_document_text and view_image. An agent can pick it out of the large sibling set without opening a 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 both positive routing (plain text, Markdown, CSV, JSON, source code) and explicit negative routing with named alternatives for PDF/Office (read_document_text) and images (view_image). It also tells the agent how to continue when the file is larger than one call, which is the main edge case.

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 single destructiveHint=false annotation: it discloses the failure modes (NAME_CONFLICT for an existing sibling name, NOT_FOUND for trashed items), the required files:write permission, the retry-safety mechanism, and that the updated node is returned.

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, each carrying distinct information: purpose, error behavior, return value, alternatives, and prerequisites. The core purpose is front-loaded with no filler or repetition 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?

An output schema exists, yet the description still notes that the updated node is returned, and it covers the mutation-specific concerns (permissions, conflict errors, retry safety) an agent needs before calling.

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 real meaning by establishing that node_id and absolute path are alternative identifiers and that idempotency_key exists for retry safety rather than ordinary calls. It does not, however, say what happens if both identifiers are supplied.

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 resource (rename one file or folder), plus the key scoping fact that it is in-place and that the target is identified by node_id or absolute path. It is immediately distinguishable from move_nodes, which is named explicitly.

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

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

Explicitly routes the agent: use move_nodes to relocate, call this once per item to rename many, and pass idempotency_key to make retries safe. Both the when-to-use and the when-to-use-something-else conditions are stated.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating lookup. The description adds the useful constraints that the path must be absolute and is case-sensitive, plus the virtual-root convention, but it says nothing about failure behavior for unresolvable paths or about resolution relative to aliases/symlinks.

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 every clause (absolute, case-sensitive, root convention) carries information an agent needs. 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 read-only lookup with a declared output schema, the description is nearly sufficient; return-value shape need not be explained. The only meaningful gap is the absence of any note on behavior when the path is invalid or not found.

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

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

Schema description coverage is 100% and the parameter already documents 'absolute case-sensitive Gopan path ... / is the root'. The description restates the same facts rather than adding new meaning such as escaping rules, trailing-slash handling, or max depth, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Resolve an absolute ... path to a node ID'), making the input and output unambiguous. It is clearly distinct from siblings like get_file_info or list_files, though it does not name any sibling to differentiate itself explicitly.

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

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

The input-to-output mapping ('path to node ID') implies the use case: converting a known path into an ID for other calls. However, there is no explicit when-to-use guidance, no mention of alternatives such as get_file_info, and no statement about what happens when the path does not resolve.

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 single destructiveHint annotation by disclosing rename-on-conflict behavior, all-or-nothing semantics, required permission scope, and the retry-safety contract of idempotency_key. The only gap is that it doesn't say whether restored items retain sharing/link state or how conflicts are surfaced.

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

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

Four dense sentences with no filler, front-loaded with purpose and the source of IDs. Slightly over-packed—conflict, atomicity, permission, and idempotency are compressed into one paragraph—but every clause carries 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?

All the risk-relevant behavior of a mutation tool is covered: conflict handling, atomicity, permission, and retry semantics. The 'Returns the restored nodes' line is mildly redundant given the output schema, but it costs nothing.

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 would be 3; the description still adds real meaning by tying node_ids to list_trash output and by framing idempotency_key as a retry-safety mechanism rather than a generic key.

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 ('Restore one or more items from the trash to their original folders') plus the source of the identifiers ('using IDs from list_trash'). It is clearly distinguishable from siblings like trash_nodes, list_trash, and batch_nodes.

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 list_trash as the prerequisite source of IDs and names batch_nodes as the alternative when per-item results are needed, with the condition ('All-or-nothing') that selects it. Also states the required permission files:delete.

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, the description discloses the permission needed (shares:write), that in-flight uploads are rejected, and idempotency support. It does not state what happens to files already uploaded or errors on a nonexistent request_id, but the annotation burden is mostly covered.

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

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

Two sentences, front-loaded with the action and immediate effect, then prerequisites. 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 an output schema present, return values need no explanation, and the description covers permissions, side effects, and retry behavior. Only the request_id format is left undocumented.

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 0%, so the description must compensate. It explains that idempotency_key enables safe retries, but says nothing about the format or source of request_id beyond the resource it identifies.

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?

A specific verb and resource are stated: 'Close a file request link.' The word 'file request' separates it from revoke_link and revoke_share, though no sibling is explicitly named as an alternative.

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

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

The consequence ('uploads in progress are rejected') points to when the tool is appropriate, but the description never says when to prefer it over revoke_link, revoke_share, or list_file_requests, leaving routing implicit.

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 annotation already signals mutation, but the description adds real context: the effect is immediate, the URL begins returning 404, and the call requires the shares:write scope. Idempotency support is also disclosed, which matters for retry behavior. What's missing is whether the revocation is reversible.

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?

A single front-loaded sentence with no filler: the action, its effect, the permission requirement, and the idempotency trait each earn their 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 two-parameter mutation with an output schema, the essentials are covered: effect, auth scope, and idempotency. The remaining gap is the meaning/source of link_id, which an agent must guess at.

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 0%, so the description must carry parameter meaning. It does explain the idempotency_key parameter's purpose ('supports idempotency'), but link_id is never described – no format, no note on where to obtain it. Partial compensation for the coverage gap.

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 pairs a specific verb with a specific resource: 'Revoke a direct URL'. That distinguishes it reasonably from create_link and clip_url, though it doesn't say how it differs from the closely related revoke_share and revoke_file_request siblings.

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

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

Usage is implied rather than stated: it's the inverse of link creation and only applies to direct URLs, which hints at the boundary with share/file-request revocation. There is no explicit 'use this instead of X when Y' guidance despite three revoke-family 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 destructiveHint=true, so the description's value-add is the permission requirement (shares:write) and idempotency support, plus 'immediately' signalling no grace period or undo. That is meaningful operational context beyond the annotation. It stops short of saying what happens to existing downloads or whether revocation is reversible.

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, action first, constraints second. Nothing redundant and nothing buried.

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?

An output schema exists, so return values need no explanation, and the destructive nature plus auth requirement are covered. However, for a destructive two-parameter tool with zero schema descriptions, the undefined share_id and idempotency_key handling leave the definition only minimally sufficient.

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

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

Schema description coverage is 0% for two parameters. The description never explains what share_id refers to (share token vs numeric id) or how idempotency_key should be supplied and reused across retries. Mentioning 'supports idempotency' gestures at the parameter without giving usable semantics, so the coverage gap is not compensated.

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: 'Revoke a share URL immediately.' An agent knows this removes a share. It does not differentiate from sibling revoke_link, so an agent must infer whether a share and a link are the same object, which is a real ambiguity in this toolset.

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 only implied by the verb. There is no statement of when to revoke a share versus revoke_link, or when to use create_share/list_shares first to confirm the target. The 'immediately' qualifier hints at urgency but gives no decision criteria.

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

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

readOnlyHint=true already declares the safety profile, yet the description still adds real behavioral detail: matching is literal and case-insensitive (no regex or fuzzy behavior), only a snippet around the FIRST match is returned, and the PDF page accompanies it. The scanned/OCR exclusion is a concrete capability boundary. It does not mention result caps or how many files are scanned, which is the remaining gap.

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 core verb and resource, followed by matching semantics and then the exclusion. Nothing is redundant or padded.

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

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

The output schema covers the return shape, and the description explains match behavior, so the essentials are present for a 2-parameter tool. It never states the search scope (all files across the drive vs. a folder), result-count limits, or whether paging is expected, which an agent would want before calling.

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 (query with a minimum-length rule, cursor with next_cursor semantics). The description's case-insensitive literal-substring note does inform how to craft the query, but it adds only modest meaning beyond the schema, so the baseline of 3 holds.

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 ('Search files by the text inside them') and enumerates supported formats (PDF, Office, OpenDocument, plain text, code), so it is clearly content search rather than name search. It stops short of naming siblings like search_files, read_text_file or read_document_text, leaving the boundary to be inferred.

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 matching semantics ('literal substring, case-insensitive') and one explicit exclusion ('Scanned images are not searchable'), which helps an agent avoid a fruitless call. There is no statement of when to prefer this over read_document_text or search_files, and no prerequisites or limits 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 readOnlyHint annotation by disclosing the 200-result page cap, the presence of next_cursor for continuation, and the required scope 'files:read'. The returned field list (id, kind, size, path) is slightly redundant with the output schema, which keeps this from a 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?

Three dense sentences with the core behavior front-loaded, followed by result shape and then routing to alternatives. No wording is padding.

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

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

Covers scope, match semantics, pagination, permissions and sibling differentiation, and since an output schema exists it does not need to describe return values in depth. 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; the description still adds meaning by specifying case-insensitive substring matching over names and that the search spans the whole drive or the credential's folder scope. It does not restate cursor semantics, but the schema already documents those.

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 files and folders'), plus the matching scope ('anywhere in the drive or inside the credential's folder scope') and match rule ('whose name contains the query, case-insensitive'). It also explicitly distinguishes itself from search_file_contents (content search) and list_files (single folder listing), so an agent can pick it without opening a 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?

Names both alternatives and the exact condition that selects each: use search_file_contents for text inside PDFs/Office/text files, use list_files to enumerate a single folder. The 'matches names only' clause is an explicit when-not statement.

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 annotations already declare readOnlyHint=true, so safety is covered. The description earns its keep by disclosing the non-obvious semantics that 'available' can overstate what a commit will accept and that quota is enforced at commit time — a behavioral trait no structured field conveys. It does not discuss refresh cadence or caching, which would have pushed it to a 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?

Two sentences, no filler. The inventory of returned values comes first and the quota caveat is placed last as the operative warning. Every clause carries information the agent needs.

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 an output schema present, the description need not enumerate return field semantics, and its two sentences plus readOnlyHint are sufficient for a zero-argument tool. The only gap is the absence of any pointer to prepare_upload or get_upload_status, which would fully situate it in the transfer workflow.

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 for the description to disambiguate and the baseline applies. No misleading parameter hints are offered.

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 ('Get') and enumerates exactly what is returned: account quota, used/reserved/available bytes, active uploads, and transfer limits. An agent can immediately tell this is a read-only account-level capacity snapshot rather than a per-file or per-upload query like get_upload_status. It stops short of naming siblings, but the resource is unambiguous.

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

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

Usage is only implied. The caveat that available space is advisory and the final commit enforces quota hints that this is a pre-flight check, but the description never says 'call this before prepare_upload' or points to get_upload_status / list_jobs for per-transfer detail. No explicit when-not-to-use guidance is present.

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

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

The single destructiveHint annotation only tells the agent this is a write; the description goes far beyond it by disclosing soft-delete semantics, a 30-day retention default, in-app undo via activity log, all-or-nothing atomicity, a success-only return, the files:delete permission requirement, and the idempotency_key retry pattern. These are the operational facts an agent needs before mutating data.

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

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

Four dense sentences, front-loaded with the core action, followed by safety semantics, then the alternative tool, then prerequisites. Nearly every sentence earns its place; only 'returns success' is slightly redundant against the output schema, and the all-or-nothing clause is terse to the point of being clipped.

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 mutation with only a destructiveHint annotation, the description supplies everything an agent needs: reversibility, retention window, atomicity, permission scope, retry safety, and the sibling to use for dry runs. Return values are covered by the existing output schema, so 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?

Schema coverage is 100%, so the baseline is 3, but the description earns more: it clarifies that node_ids may be files OR folders and that folder contents are included recursively, and it explains the purpose of idempotency_key (making retries safe) beyond the schema's bare 'stable retry key' text. Minor remaining gap: no mention of practical batch-size limits.

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 — moving files or folders (with recursive contents) to the trash — and immediately distinguishes it from siblings by naming list_trash, restore_nodes, and batch_nodes. An agent can identify the exact 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?

Explicitly routes the agent: use this tool for bulk trash with all-or-nothing semantics, but use batch_nodes instead when per-item results or a dry-run preview are needed. It also names the recovery path (list_trash / restore_nodes), so the agent understands the downstream workflow.

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