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

With no annotations, the description carries the full burden. It usefully discloses irreversibility and the effect of omitting trash_id, but does not mention required permissions, confirmation behavior, or what happens to other trash items when emptying the bin.

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

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

Two short sentences, front-loaded with the core action and the irreversibility warning. Every sentence carries useful information.

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

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

For a simple one-parameter destructive tool with no output schema and no annotations, the description covers the essential action, the two modes, and irreversibility. It could still say more about permissions or confirmation, but is largely complete 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 100%, and the schema already explains that trash_id should be omitted to empty the whole bin. The description restates that behavior but adds no format, validation, or edge-case 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?

The description states a specific verb and resource: 'Permanently delete one item from the trash bin, or empty the whole trash bin.' It distinguishes the operation from ordinary deletion and restore/list siblings by emphasizing permanence and the whole-bin mode.

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 'irreversible' and the two supported modes, but it does not explicitly say when to use this instead of delete or restore_from_trash, nor does it name alternatives or 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?

No annotations exist, so the description carries the full behavioral burden. It usefully discloses the trailing-slash destination rule, but says nothing about what happens when the destination already exists and `overwrite` is false (error vs. auto-rename), whether metadata is preserved, or required permissions. For an unannotated mutation tool, that is a significant 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?

Two short sentences, purpose first, the non-obvious path convention second. No filler, nothing repeated from structured fields.

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

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

With no annotations, no output schema, and a mutation that can overwrite data, the description should state collision/overwrite behavior and whether output is a new path. It covers paths but leaves the riskiest behavior undefined.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine meaning for `to` beyond the schema's "folder ending with '/'": it spells out that a trailing slash means "into this folder, same name," which resolves the ambiguity of how the copy is named. `from` and `overwrite` add nothing 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 and resource ("Copy a file or folder") and covers both files and folders explicitly. It does not name or contrast with the sibling `move`, which has near-identical destination semantics, so an agent must infer the distinction from the tool name alone.

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

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

No explicit when-to-use, when-not, or alternative routing, despite `move` and `upload_file` being plausible alternatives. The intent is implied by the self-evident name, but nothing states that source is preserved or when to prefer this over `move`.

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 no annotations, the description carries the full behavioral burden. It helpfully discloses that missing parent folders are created, but it does not say what happens if the folder already exists or what permissions/errors may apply.

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?

It is one efficiently sized sentence with the key action front-loaded. There is no redundant or wasted text.

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

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

For a simple one-parameter mutation tool this is minimally adequate, and the parent-folder behavior is useful context. However, without annotations or an output schema, it should ideally state what happens when the target folder already exists and what the tool returns.

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 path parameter has 100% schema description coverage and includes an example. The description adds the parent-creation behavior but does not add further meaning to the path parameter itself.

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?

It states a specific verb and resource: creating a folder. The parenthetical adds important scope, but it does not explicitly distinguish this from related siblings such as upload_folder.

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 no guidance on when to use create_folder versus upload_folder or other adjacent tools. It also does not mention prerequisites or when not to use it.

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

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

With no annotations, the description carries the full burden: it usefully discloses the default share type and that public shares yield a link in the response. It omits what permissions are needed, what happens if a share already exists (idempotency), and what non-link shares return, which are meaningful gaps for a mutation tool.

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

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

Two short sentences, front-loaded with the verb and resource, with the default called out parenthetically. No filler and 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?

Eight parameters, no output schema, and no annotations mean the description should be doing more: it explains the return only for public shares and says nothing about recipient-side effects (notification to share_with, note delivery) or failure modes. Adequate but with clear gaps for a mutation with this many optional params.

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

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

Schema description coverage is 100%, so baseline is 3. The description only echoes the link default and the link return value; it adds nothing about password/label being link-only, expire_date format, or permissions semantics that the schema does not already state.

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 (share) plus the resource (file or folder) and enumerates the three sharing modes with their default, which lets an agent distinguish it from siblings like update_share or delete_share without opening the schema.

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

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

The description implies this is the creation path for shares versus update_share/delete_share, but never names those alternatives or states when to choose this over them. An agent can infer intent but is given no explicit routing rule or prerequisite (e.g., file must exist, must be owner).

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 no annotations, the description carries the full behavioral burden and does disclose the critical trait: items go to the owner's trash bin and can be restored. The 'of their owner' detail is useful for shared content. It omits permission requirements, partial-failure behavior when deleting multiple paths, and whether trashed items still occupy space or appear in listings.

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 action and target, with the recovery hint in parentheses. Zero waste and no redundancy with structured fields.

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 mutation tool with no annotations and no output schema, the description covers the essential reversibility fact, which is the most important thing an agent needs. It leaves gaps on permission prerequisites, error/partial-failure semantics for multiple paths, and what the response contains.

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 single 'paths' array parameter is already documented in the schema, and the description adds no format, relative-vs-absolute path rules, or multi-path semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (Delete) and resource (files or folders), which disambiguates the generic tool name 'delete' from siblings like delete_share and clear_trash. It doesn't explicitly exclude those siblings, but the file/folder scoping does the work.

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?

Implies usage by naming restore_from_trash as the recovery path, which tells the agent the deletion is reversible. However, there is no explicit when-to-use vs clear_trash (permanent removal) or delete_share, and no guidance on required permissions or preconditions.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does add one genuinely valuable behavioral fact — the underlying file is not deleted — but it omits permission requirements, whether the revocation is reversible, and what happens to users who already had access.

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 compact sentence with the destructive scope front-loaded and the non-destructive caveat immediately after. Every clause earns its place; there is no filler.

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

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

For a one-parameter destructive tool with no annotations and no output schema, the description covers the essential ambiguity (does this delete the file?) and the ID source. Only the permission/auth and reversibility details are missing, which is a modest gap.

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

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

Schema coverage is 100% (the lone `share_id` param is documented as "Share ID"), so the baseline is 3. The description goes beyond the schema by telling the agent where to obtain the ID (`list_shares`), which is real semantic value for a single-parameter tool.

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 ("Remove") and resource ("a share or public link"), and the trailing clause "the file itself stays" separates it from the sibling `delete`, which presumably removes the file. It stops short of naming `update_share`/`create_share` as the siblings it is not, but an agent can still tell what this tool does.

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

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

The parenthetical "(ID from list_shares)" implies the workflow of listing shares first, which is useful context. However, there is no explicit when-to-use/when-not guidance, no statement about when to prefer `update_share` (e.g., to revoke access without deleting the link), and no prerequisites mentioned.

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

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

No annotations are provided, so the description carries the full burden. It discloses the returned information categories (quota, server, user), which implies a safe read-only operation, but it does not explicitly state read-only behavior, authentication requirements, or output format.

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 wasted words. The trailing 'server and user' is slightly ambiguous in phrasing, but the sentence is efficient overall.

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

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

With no output schema, annotations, or parameters, the description must explain what comes back. It lists the key return categories (used quota, available quota, server, user), which is sufficient for a simple read-only info tool, though the 'server and user' phrasing could be sharper.

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 per the baseline this starts at 4. The description correctly adds no parameter guidance because none exist.

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

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

The description names the resource and scope precisely: storage info for the Nextcloud account, including used/available quota, server, and user. It is clearly distinguishable from sibling file-operation tools. It lacks a strong action verb ('Storage info of...' is noun-phrase), which keeps it from 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 implied by the nature of the tool (check account storage/quota), and no sibling tool offers an alternative quota path. However, the description never states when to call it, when not to, or any prerequisites, leaving the agent to infer.

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 no annotations, the description carries the full behavioral burden; it does disclose that folders are fetched recursively and in parallel and that the destination may be a file or an existing directory. It says nothing about permission requirements, whether existing local files are replaced (the overwrite default lives only in the schema), partial-failure behavior, or what is returned on success.

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

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

Two tight sentences with zero filler; the core action is front-loaded and the destination rule follows immediately. Nothing is repeated from the schema descriptions.

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

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

For a three-parameter, no-annotation, no-output-schema tool, the description covers the action and destination semantics but leaves out overwrite behavior and result reporting. Adequate for a straightforward transfer tool, but it does not fully compensate for the missing annotations.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics beyond the schema for local_path: it clarifies that a trailing '/' or an existing folder means download-into, versus a plain path meaning target file. It does not explain how path interacts with local_path for recursive folder downloads.

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

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

States a specific verb and resource ('Download a file or a whole folder ... to this machine') and adds scope details (recursive, parallel) that make the operation concrete. It does not name or differentiate from siblings like read_file, so an agent must infer which retrieval path to use.

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 / when-not-to-use guidance and no mention of alternatives such as read_file or get_file_info. The agent must infer usage purely from the tool name and the folder-recursion detail.

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 no annotations, the description must carry behavioral disclosure. It usefully signals this is a metadata read by listing fields, but does not state read-only safety, required permissions, error behavior, or whether folders and files are treated differently.

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 short sentence enumerating fields, front-loaded with the core purpose. No filler; every listed item is relevant.

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

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

For a one-parameter tool with no output schema, the description gives the main return contents, which is helpful. It still omits return format and error/read-only details, but is largely complete for this simple operation.

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

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

Schema coverage is 100% and the single path parameter includes an example, so the schema already provides semantics. The description adds no path-specific detail beyond 'file or folder', leaving baseline 3.

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

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

The description names the resource (file or folder) and enumerates the returned metadata (size, dates, type, file ID, permissions, web link), so the agent knows it retrieves metadata rather than content. It does not explicitly contrast with siblings like read_file or list_files, so it stops short of full 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?

No when-to-use or when-not-to-use guidance is provided. The agent can infer it is for metadata inspection, but there is no explicit routing against read_file, list_files, or search_files.

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

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

With no annotations, the description carries the full burden and adds useful context about the path root and accepting Files app URLs. However, it never discloses permissions/auth requirements, whether hidden or shared items are included, error behavior for missing paths, or what the listing contains beyond names — significant gaps for a read tool with zero annotation coverage.

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

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

Two compact sentences, front-loaded with the core action followed by the path convention and a concrete example. No filler or redundancy.

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

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

For a read-only listing tool with full schema coverage and no output schema, the description covers the essential path semantics and one practical input form. Missing tool-selection guidance and listing-content details keep it from a 5.

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

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

Schema description coverage is 100%, so all four parameters are already documented including the sort enum and pagination. The description adds the URL-form example for path, but nothing about sort, limit, or offset beyond the schema — baseline 3 is appropriate.

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

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

States a specific verb and resource ("List files and folders at a path") and scopes it to one location, which implicitly contrasts with siblings like search_files and recent_files. It does not explicitly name an alternative, 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?

Usage is implied by the path-based framing but never stated: there is no guidance on when to use this versus search_files, recent_files, or get_file_info. The only concrete guidance is about path format, not tool selection.

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

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

With no annotations, the description carries the full burden. 'List' implies a read-only operation and the parenthetical hints at the returned shape (paths where the items appear), which is useful, but there is no statement about permissions, pagination, ordering, or whether folders are recursed.

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

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

One tight sentence with the resource and scope front-loaded, no filler. The trailing parenthetical 'paths where they appear' is slightly opaque but does not waste space.

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

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

This is a parameterless, read-only listing tool with no output schema, so the description need only convey what it lists and the sharing direction — which it does. The main residual gap is not distinguishing itself from list_shares or indicating result shape beyond 'paths'.

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 per the baseline there is nothing for the description to disambiguate. No parameter-level value could be added, and none is missing.

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

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

States a specific verb (list) and resource (files and folders shared with the current user), scoping direction of sharing (incoming, not outgoing). It does not name the sibling list_shares — which is the natural point of confusion (shares you created vs. shares others made for you) — so the differentiation 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?

The phrase 'shared with the current user' implies the use case, but there is no explicit instruction on when to use this instead of list_files, search_files, or list_shares, and no exclusions or prerequisites. Usage is inferable but not guided.

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 no annotations, the description carries the full burden. It usefully discloses the recursive expansion behavior ('every share inside a folder at any depth'), which is the main behavioral risk, but says nothing about read-only nature, permissions, result size, or pagination.

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 wasted words; the scope and the subfiles modifier both appear immediately. 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?

For a two-optional-parameter read tool with full schema coverage, the description covers both modes of operation and the recursive case adequately. The absence of annotations and an output schema leaves minor gaps around return shape, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description restates the path/subfiles interaction almost verbatim, adding marginal clarity but no new meaning such as path format or default behavior.

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 shares') and scopes it to shares 'made by the user', which implicitly distinguishes it from the sibling list_shared_with_me. It stops short of naming that sibling explicitly, so an agent must infer the direction of the relationship.

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 two modes it describes ('all, or of one path') and by the subfiles expansion, but there is no explicit when-to-use or when-not-to-use guidance and no sibling is named. The agent can infer intent but gets no routing help against list_shared_with_me or get_file_info.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. 'List' implies a non-mutating read and 'newest first' documents ordering, but it does not cover pagination behavior, auth/permissions, or returned item 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?

The description is a single compact sentence with the verb and resource front-loaded, plus a useful ordering detail. There is no wasted text.

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

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

For a low-complexity read-only listing tool, the description plus fully documented schema is nearly sufficient. The remaining gap is that there is no output schema and no annotations, so return item fields and pagination details are left implicit.

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 sole parameter, limit, is fully documented in the schema with its default. The description adds no parameter-specific guidance, so the schema does the heavy lifting and 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 and resource: list items in the trash bin. It also adds the ordering scope, newest first, and naturally distinguishes this read/list operation from siblings such as restore_from_trash and clear_trash.

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

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

The intended use is implied clearly: view what is currently in the trash. However, it does not explicitly say when to use this versus restore_from_trash or clear_trash, nor does it provide exclusions or prerequisites.

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

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses that a browser window opens, SSO works, an app password is issued and saved, and the tool waits up to 2 minutes before continuing in the background and returning the login URL. This gives an agent a clear picture of side effects, timing, and fallback 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?

The definition is front-loaded with the primary behavior and then adds the fallback path and usage trigger. Every sentence provides actionable information with no filler.

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

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

No output schema or annotations exist, but the description covers the key return behavior (login URL), the 2-minute wait/background continuation, and the manual credential alternative. Nothing essential for an agent to invoke this authentication tool 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 all three parameters are already documented. The description still adds practical meaning by tying login_name and app_password to the no-browser mode and by telling the user where to obtain an app password (Settings → Security → App passwords); server_url behavior is left 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?

The description opens with a specific verb and resource: 'Sign in to Nextcloud with Login Flow v2.' It clearly identifies this as an authentication tool, distinguishing it from the file-operation siblings without requiring schema inspection.

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 says when to call it: 'Call this when other tools report that the user is not logged in.' It also names the no-browser alternative and tells the user to pass login_name and app_password in that 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?

With no annotations, the description carries the full behavioral burden. It discloses the trailing-slash destination convention, but does not explain overwrite behavior, permissions, source removal, failure modes, or what happens when the destination already exists.

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 core purpose front-loaded and the key destination-path rule immediately after. There is no wasted 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?

The definition is adequate for a simple move operation when combined with the fully described schema. However, for a mutation tool with no annotations and no output schema, it leaves important behavioral details such as overwrite effects and error conditions 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 the baseline is 3. The description adds useful meaning beyond the schema by clarifying that a destination ending in '/' means 'into this folder, same name,' though it does not discuss the overwrite parameter.

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

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

The description states a specific verb and resource: 'Move or rename a file or folder.' It clearly identifies the operation, including renaming, but does not differentiate the tool from siblings such as copy or delete.

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

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

The description gives no explicit guidance on when to use move rather than copy, when renaming is preferable, or what prerequisites apply. It only describes one destination-path convention, which is parameter semantics 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the 200 KB truncation, but says nothing about error behavior for missing paths, encoding assumptions, binary-file rejection, or permission requirements — notable gaps for a read tool with zero annotation coverage.

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 compact sentence with the verb and resource front-loaded and the truncation limit attached inline. Slightly dense with the format list, but nothing 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?

For a one-parameter read tool with no output schema, the description covers what it returns and the size cap, which is enough to call it correctly. However, with no annotations, it should also say what happens on missing files or binary input to be fully complete.

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

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

Schema description coverage is 100% for the single `path` parameter, so the schema already documents it fully. The description adds only the server-side framing implicit in the schema, so baseline 3 applies.

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

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

States a specific verb (Read) and resource (text file) and names the file types covered along with what is returned (contents). This clearly separates it from siblings like get_file_info (metadata) and download (transfer) without requiring the schema to be opened.

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 parenthetical list of text formats implies the appropriate use case (text-like files) but never states when to prefer this over download or get_file_info, nor does it warn about binary files. Usage is inferable 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?

With no annotations, the description carries the behavioral burden. It discloses useful traits such as newest-first ordering and server-side date filtering, but it omits safety profile, pagination behavior, error cases, and whether results are filtered by permissions or folder existence.

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

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

The description is a single, front-loaded sentence with zero waste. The parenthetical adds useful mechanism context without bloat, and every part of the statement earns its place.

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

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

For a simple three-parameter listing tool with full schema coverage and no output schema, the description covers the core concept but remains minimal. It does not describe return shape, edge cases, or how the recursive folder lookup behaves, leaving some gaps an agent might need.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters and their defaults. The description adds the overall scoping intent (recent modification) but does not provide any additional parameter-level 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?

The description clearly states the resource (files), the selection criterion (modified recently), and the ordering (newest first). It implies a server-side date search, but it does not explicitly distinguish itself from sibling tools like search_files or list_files.

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

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

There is no explicit guidance on when to use this tool versus search_files, list_files, or other file-listing siblings. The phrase 'server-side search by modification date' hints at the mechanism but does not provide usage conditions or 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?

With no annotations, the description carries the burden; it does disclose the key outcome (item goes back to its original location). However, it omits whether restoration fails when the original location exists, whether it requires write permissions, or whether expiry applies — meaningful gaps for a mutation tool.

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

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

A single sentence with zero filler, front-loaded with the action and outcome. Nothing to trim.

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

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

For a one-parameter tool with a fully described schema and no output schema, the description covers purpose, target, and id source adequately. Only mutation edge cases (conflicts, permissions, expiry) 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 coverage is 100% and the schema already gives the id format example. The description adds only the provenance hint ('from list_trash'), which is slightly useful but marginal — baseline 3 is appropriate.

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

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

States a specific verb (restore) and resource (item from trash), plus the destination (original location). This clearly differentiates it from siblings like list_trash, clear_trash, and delete without needing to open the schema.

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

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

The parenthetical '(id from list_trash)' tells the agent the prerequisite step for obtaining the required id, which is genuine routing guidance. It doesn't state exclusions (e.g., what to do if the original path is occupied or the item is expired), 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?

With no annotations, the description carries the full burden and does meaningful work: it discloses server-side execution, case-insensitive substring matching, newest-first ordering, and the important edge case that omitting `query` turns the tool into an unfiltered listing. It does not mention pagination beyond the schema's limit, nor whether folders are included in results, which keeps it short of 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 short sentences, zero filler, and the core search semantics are front-loaded before the edge case about omitted `query`. Every clause conveys actionable information.

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

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

For a zero-required-parameter read-only search with a fully documented schema and no output schema, this covers the essential behavior an agent needs: match rule, scope, ordering, and the no-query fallback. Gaps are minor — result field shape and pagination behavior are left unstated.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by clarifying that `query` is a substring match against the name and that `mime_type` is optional and independent of the query. It does not restate the wildcard syntax or limit bounds, but the schema already handles 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 ('Server-side search by name') plus the matching semantics (case-insensitive substring) and result ordering (newest first). It clearly distinguishes itself from read_file/get_file_info by being a search over a folder tree, though it never names the nearest sibling list_files, which also enumerates folder contents.

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?

'Without `query` lists everything matching the filter' implies a browse mode, so the when-to-use is inferable rather than stated. There is no explicit guidance on choosing this over list_files, recent_files, or get_file_info, and no note about when the MIME filter should be preferred over a name query.

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 no annotations, the description carries the full behavioral burden and delivers little beyond the name. It does not say whether the operation is idempotent, what happens if the path does not exist, whether a permission/login is required, or whether there is any return value.

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 short sentence with no filler, front-loaded with the action and object. Nothing to trim 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?

For a simple two-parameter toggle with a fully documented schema this is adequate, but the absence of annotations means error behavior and idempotency are left entirely 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 100%: the path parameter and the boolean 'favorite' (true to add, false to remove) are fully documented in the schema. The description adds nothing beyond that, so baseline 3 applies.

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

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

States a specific verb (mark/unmark) and resource (file/folder) plus the resulting state (favorite), so an agent immediately knows what the tool does. No sibling tool in the list handles favorites, so there is no real ambiguity to resolve.

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 no when-to-use context, no prerequisites, and no mention of any alternative or related tool. The agent must infer from the name alone when favoriting is appropriate.

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

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

With no annotations, the description carries the full behavioral burden and largely doesn't. It doesn't state whether this is a partial update (only supplied fields changed), whether changes are reversible, what permissions or ownership are required, or what happens on failure — only the schema hints that '' removes password/expiry.

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 sentence, front-loaded with the verb and resource, with the field list and ID hint compressed into one line. Nothing is wasted, though the parenthetical is terse enough that the 'get the ID first' step reads as an aside rather than a call-setup instruction.

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 six-parameter mutation tool with no annotations and no output schema, the description covers what can be changed and where the ID comes from, but omits update semantics (partial vs. full replace) and the authorization/error surface. Adequate to select the tool, thin for invoking it correctly on a partially populated 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 the schema already documents all six parameters, including the enum values and the empty-string removal semantics. The description only mirrors the field list, adding no syntax or format detail beyond what the schema provides; baseline 3 applies.

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

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

The description uses a specific verb ('Change') and resource ('a share') and enumerates the mutable fields, so an agent can tell it apart from create_share, delete_share and list_shares without opening the schema. It stops short of distinguishing itself explicitly from its siblings, but the meaning 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?

The parenthetical '(ID from list_shares)' gives a concrete prerequisite path for obtaining the required share_id, which is genuinely useful. There is no guidance on when not to use it (e.g. use create_share for new shares, delete_share to revoke) or on permissions needed to modify a share.

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 no annotations, the description carries the full burden. It usefully discloses that large files are chunked internally, but says nothing about permission requirements, what happens on name collisions, whether the existing file is replaced (schema covers overwrite default), or what the caller gets back.

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 action, then the two most decision-relevant behaviors. No filler or repetition.

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

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

Adequate for a 3-parameter mutation tool whose schema is fully documented, but with zero annotations the description should ideally cover the overwrite/collision case and any error or permission constraints so an agent can call it 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; the description adds real meaning by explaining that a destination ending in '/' keeps the local filename, which the schema only hints at. It still says nothing extra about local_path or overwrite beyond the schema text.

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

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

States a specific verb and resource ("Upload a local file") that clearly separates it from read-only siblings like read_file and from upload_folder. It does not explicitly name the sibling it is distinguished from, so it stops short of a 5.

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

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

The trailing-slash sentence implies a supported use case (uploading into a folder while preserving the local name), but there is no explicit when-to-use guidance versus upload_folder, download, or copy, and no mention of prerequisites such as being logged 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?

With no annotations, the description carries the full burden and does well: it discloses parallelism, recursion, that the destination folder is created under `path` using the source folder's own name, and the default skip-existing vs overwrite=true conflict policy. It omits error behavior, permission requirements, and what happens on partial failure, keeping it short of 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 short sentences, front-loaded with the core action and followed by the destination-naming and conflict behavior. No filler, no repetition of schema text.

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

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

For a 3-parameter mutation tool with no annotations and no output schema, the description covers what is uploaded, where it lands, and how collisions are handled. It leaves out return value and failure/partial-upload behavior, which an agent would want given no output schema exists.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: it clarifies that `path` is the parent under which a folder named after the local folder is created, and that `overwrite` governs skipped-vs-replaced existing files rather than merge semantics.

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 with scope: 'upload a whole local folder recursively in one call (parallel)'. This distinguishes it implicitly from upload_file and create_folder via the 'whole folder / recursive' framing, though no sibling 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?

Usage is implied by 'whole local folder recursively' versus the sibling upload_file, but the description never says when to prefer this over calling upload_file per file, nor any prerequisites such as login state or permissions.

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