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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is partly covered, but the description adds nothing: it does not explain what happens when dest_path already exists, what overwrite does, or whether a failed copy of a directory is partial. For a mutation tool with an undocumented overwrite flag, that is a real 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?

It is one short sentence, so nothing is bloated, but the single sentence is an internal implementation note ('Alias ... to support MCP server action') that conveys no information useful to a caller. Brevity here comes from under-specification rather than economy.

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?

Three parameters, two required, zero schema descriptions, no output schema, and no annotations beyond safety hints. The description should carry the load of explaining paths, overwrite semantics, and return behavior, and it does none of 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 description coverage is 0% and the description supplies no parameter meaning whatsoever. The critical semantics of overwrite (default false, presumably failing or skipping on existing destination) and the file-vs-directory behavior of source_path/dest_path are left completely unexplained.

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 only restates that it is an alias for copy_resource, a sibling tool it never explains; the actual purpose (copying a file/folder from source_path to dest_path) is inferable only from the tool name and parameter names. It does not distinguish this from nextcloud_move_item, nextcloud_copy_resource, or nextcloud_create_folder in any substantive way.

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 guidance at all. Saying it is an 'alias ... to support MCP server action' gives the agent no condition for choosing this over nextcloud_copy_resource, nor any mention of prerequisites 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?

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. But the description adds nothing beyond that: it does not say whether recursive directory copies are supported, whether an existing destination causes an error, or what the 'overwrite' default of false actually means in practice — the key behavioral question for a copy 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 front-loaded sentence with zero waste, which is structurally good. The problem is that it is under-specified rather than concise: one short clause cannot cover a mutation tool with an ambiguous overwrite flag.

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 three parameters, no output schema and 0% schema coverage, the description should explain destination-conflict behavior and directory semantics. It supplies none of that, so an agent cannot confidently call this tool correctly when the destination exists or when copying a folder tree.

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 carries the full burden of explaining three parameters and it explains none. source_path and dest_path are self-evident from their names, but 'overwrite' (default false) is genuinely ambiguous — fail vs. skip vs. silently overwrite — and the description offers no clarification.

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 (copy) and resource (file or directory), so the operation is unambiguous on its own. However, it does nothing to distinguish itself from the near-identical sibling nextcloud_copy_item (nor from nextcloud_move_resource/move_item), leaving the agent to guess which copy tool applies.

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 at all: no mention of when to prefer this over nextcloud_copy_item, no prerequisites, and no indication of what happens when the destination already exists. The agent must infer everything from the tool name.

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=false, destructiveHint=false, and openWorldHint=true, so the agent knows this is a non-destructive write to an open world. The description adds nothing beyond that — it does not say what is created, whether the target calendar must exist, whether duplicates are tolerated, or what the server returns.

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

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

It is a single short, front-loaded sentence with no filler, so structure is fine. The problem is that the one sentence carries almost no information, and the alias relationship is the only fact conveyed.

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 3 parameters at 0% schema description coverage, no output schema, and a mutation tool with no permission or format detail, the definition is far too thin. An agent would have to guess both the payload format and the correct relationship to nextcloud_create_event 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 0% and the description provides no parameter meaning at all. Critically, event_data is a bare string with no hint about whether it is JSON, iCalendar text, or something else, and calendar_url format is equally unexplained — the agent cannot construct a valid call from this description.

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

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

The description only says it is "Alias for create_event," which restates the tool name rather than explaining what the tool does. It never states that it creates a calendar event, what the event data represents, or how it differs functionally from the sibling nextcloud_create_event.

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 guidance on when to pick this alias over nextcloud_create_event, which is the key decision an agent faces given both tools exist. "To support MCP server action" is an implementation note, not a usage rule, and no prerequisites or exclusions are given.

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=false, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile exists elsewhere. The description adds no behavioral context whatsoever - nothing about naming collisions, overwrite behavior implied by idempotency, or remote-server interaction despite openWorldHint=true.

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 short, but the brevity is under-specification rather than conciseness - a single tautological sentence with no front-loaded useful content. Not verbose, but earns nothing.

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

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

A mutation tool with 3 undocumented parameters, no output schema, and 0% schema coverage needs a description that compensates; this one supplies nothing. An agent has no basis for constructing address_book_url or vcard_data correctly.

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

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

Schema description coverage is 0% across 3 parameters (address_book_url, vcard_data, filename), so the description carries the full burden and completely fails it. It names no parameter, gives no format for vcard_data (raw vCard string? base64?), and no hint that filename is an optional override.

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 restates the tool name and title ('create_contact operation') without adding any specificity about what a contact is in this system or where it lands. Only the tool name itself conveys verb+resource; the sentence contributes nothing an agent couldn't infer from 'nextcloud_create_contact'.

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 indication of when to use this versus siblings like nextcloud_create_share, nextcloud_create_calendar_event, or nextcloud_list_address_books. No prerequisites (does the address book need to exist? does list_address_books need calling first?) 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?

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), lowering the bar. The "MKCOL" reference adds a genuine technical signal — WebDAV collection creation, which implies parents are not auto-created and an existing collection yields an error — but the description never states that behavior explicitly, nor what happens on conflict.

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, front-loaded sentence with no filler. It is efficient, though its brevity borders on under-specification rather than tight scoping.

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

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

For a mutation tool with no output schema and a fully undocumented required parameter, the definition should cover path format and existing-directory/conflict behavior. Neither is addressed, so an agent cannot reliably construct a correct call.

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 single `path` parameter is entirely undocumented in both schema and description. The description does not say whether the path is absolute or relative to the user root, whether a leading slash or trailing slash is expected, or which parent it is created under.

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 ("Create a directory") and adds the WebDAV method (MKCOL), so the operation is unambiguous. It does not distinguish itself from the sibling nextcloud_create_folder or nextcloud_create_resource-style tools, leaving the agent to infer the difference.

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 guidance on when to use this versus nextcloud_create_folder, which appears to overlap directly, nor on prerequisites (parent existence, permissions). The agent must guess which creation tool to pick.

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=false, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only 'with ICS data' and says nothing about permissions, what calendar_url must point to, or how idempotency keys are derived from event_data/filename.

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 single sentence is front-loaded and has no wasted words. It is too terse rather than rambling, but the structure is at least clean and easy to parse.

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

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

For a write tool with three parameters at 0% schema description coverage and no output schema, the description should clarify the ICS string format, the calendar_url target, and the filename default. None of that is present, leaving the agent to guess at call shape.

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 explain the three parameters. It only hints that `event_data` is ICS data and leaves `calendar_url` and `filename` completely undefined, including whether `filename` is derived from the event UID or controls storage naming.

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

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

States a specific verb and resource ('Create an event') and adds the notable detail that the payload is ICS data. However, it does not distinguish itself from the sibling tool `nextcloud_create_calendar_event`, so an agent cannot tell which creation tool is correct without opening both schemas.

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

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

There is no guidance on when to use this tool versus `nextcloud_create_calendar_event` or the other create_* siblings. Usage is only implied by the tool name and the word 'event'.

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=false, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds nothing behavioral beyond that: it never says whether the parent path must exist, whether an existing folder is overwritten or errors out, or whether creation is recursive. Calling it an 'alias' conveys equivalence, not 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?

It is a single short sentence with no filler, so it is certainly concise, but the brevity comes from omission rather than compression. Nothing is front-loaded because there is no substantive content to order.

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

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

For a mutation tool with no output schema and a completely undocumented required parameter, the description supplies neither behavior nor input semantics. An agent cannot verify success conditions, error cases, or the meaning of the path argument from the definition as written.

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 0% and the single 'path' parameter is documented nowhere. The description provides no meaning for path — absolute vs relative, whether it names the new folder or its parent, or the expected delimiter/format — so the agent must guess the most consequential input the tool takes.

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 only says it is an alias for create_directory; the actual verb+resource ('create a folder') is inferred from the title and the aliased sibling. It identifies the tool's identity but does not describe what the operation does or how it differs from nextcloud_create_directory, which remains a live sibling in the same 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?

No guidance on when to use this tool versus nextcloud_create_directory, which it explicitly declares itself an alias of. The agent is left with two indistinguishable tools and no rule for choosing between them, and no prerequisites (parent existence, permissions) 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?

Annotations already disclose non-read-only, non-idempotent, open-world, non-destructive behavior, but the description adds nothing on top: it does not say whether shares are public links or user/group shares, what permissions mean, whether the operation is repeatable, or what the returned share looks like. For a mutation tool with a 0% documented schema, this is a substantial 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?

One sentence with no waste, but it is under-specified rather than concise — no information is front-loaded because none exists.

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

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

A write tool with three parameters, no output schema, no enum hints, and 0% schema coverage receives no compensating explanation. An agent cannot reliably choose share_type or permissions values from this definition.

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% and the description provides no parameter meaning at all. The critical parameters 'share_type' (integer, default 3) and 'permissions' (integer bitmask, default 1) are opaque without explanation, and 'path' is undocumented beyond its type.

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 'Create a share.' merely restates the tool name and title. It does not say what is being shared (file, folder, link), what kind of share results, or how it differs from siblings like nextcloud_create_directory or nextcloud_copy_resource.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as nextcloud_list_shares (to inspect existing shares) or nextcloud_delete_share. The agent must infer everything from the name.

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, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered by structured data. The description adds nothing beyond the alias fact – no statement about irreversibility, confirmation requirements, or what happens when path does not exist.

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 a single short, front-loaded sentence with no padding, so structurally fine. However, the one sentence spent on alias metadata does not earn its place against the missing explanation of what gets deleted and what path means.

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 destructive operation with no output schema and an entirely undocumented parameter, so the description carries most of the burden – yet it covers neither the affected resource type nor the path format nor error behavior. The alias note is the only useful content.

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?

There is a single required path parameter with 0% schema description coverage, so the description must explain its format and semantics. It says nothing at all about path – not whether it is root-relative, URL-encoded, or whether it addresses files versus folders.

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 only says it is an alias for delete_resource; it does not state what an "item" is (file, folder, share, calendar, contact) or what resource domain it operates on. A reader can infer deletion from the name and the alias pointer, but the description itself adds no scope beyond the title.

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?

Naming delete_resource does tell the agent the two calls are functionally equivalent, which is faint routing value. But there is no guidance on when to prefer delete_item over the direct delete_resource sibling, nor any prerequisites 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the description adds no safety information beyond structured fields. It does not say whether directory deletion is recursive, whether deletion is permanent or goes to trash, or what permissions are required.

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 short sentence with no wasted words. It is front-loaded, though its brevity contributes to the missing details noted in other dimensions.

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 file-system mutation with no output schema and 0% schema description coverage, the description is too sparse. It omits path format, recursive behavior, trash semantics, and sibling differentiation, leaving significant operational gaps.

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

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

Schema description coverage is 0% and the single path parameter has no description in the schema. The tool description does not clarify whether path is absolute or relative, how to specify root paths, or any format constraints, so it fails to compensate for the schema 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 states a specific verb and resource: delete a file or directory. However, it does not distinguish this tool from the sibling nextcloud_delete_item, which appears to target the same resource type, leaving ambiguity for tool selection.

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 guidance on when to use this tool versus nextcloud_delete_item, nor any prerequisites, exclusions, or context about deletion behavior. The agent must infer usage solely from the name and 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?

Annotations already declare destructiveHint=true, idempotentHint=true, openWorldHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — no note on permanence, permission requirements, or effect on recipients — so it contributes no behavioral context beyond the annotations.

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

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

It is short and front-loaded, but the brevity reflects under-specification rather than efficiency; the single sentence carries no actionable information beyond 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 destructive mutation with one undocumented parameter and no output schema, the description is far too thin. It should at least identify the share_id source, destructiveness, and whether deletion affects access for recipients.

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%, and the description does not explain what share_id is, where to obtain it, or its expected format. With one required parameter completely undocumented in both schema and description, the description fails to compensate 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 “Delete a share.” merely restates the tool name and title without adding scope, target, or distinguishing detail from siblings such as nextcloud_delete_item or nextcloud_delete_resource.

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

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

It gives no guidance on when to use this tool versus alternatives, no prerequisites, and no indication of which kind of share (file, calendar, contact) it applies to.

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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description does add one non-obvious behavioral fact — that properties are derived by enumerating directory contents — but says nothing about what properties come back, cost on large directories, or behavior when the path is a 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 short sentence with the verb front-loaded and no filler. It is efficient, though the brevity comes at the cost of substance rather than from disciplined editing.

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

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

With no output schema, the description is the only place an agent could learn what 'properties' actually contains (size, mtime, etag, permissions?), and it omits that entirely. For a helper whose return shape is undefined anywhere else, the definition is under-specified.

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 0% for the single 'path' parameter, so the description must carry the burden and it does not: no format (WebDAV vs local), no note that the default '' means the user root, no trailing-slash or file-vs-folder semantics. 'A path' adds nothing beyond the schema key name.

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 verb ('get') and resource ('properties of a path'), but 'properties' is never defined and the phrase 'by listing its contents' is an implementation detail rather than a purpose statement. An agent cannot tell from this how it differs from sibling nextcloud_list_contents or nextcloud_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 guidance on when to use this instead of nextcloud_list_contents, nextcloud_list_files, or nextcloud_read_file, despite those siblings covering overlapping ground. The only hint, 'by listing its contents', is descriptive rather than prescriptive.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds only the implicit notion of the authenticated user ('current'), without stating auth requirements, what is returned, or failure behavior for unauthenticated calls.

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 wasted words and the key qualifier ('current') up front. It is terse to the point of under-specification, but that is penalized in completeness rather than here.

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

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

With no output schema, the agent has no idea which user fields are returned (id, display name, email, groups?), which is exactly what a 'get info' tool should hint at. Given the trivial parameter surface and full annotation coverage, this gap is the only meaningful one, but it is 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?

The schema has zero parameters, so the baseline is 4 and there is nothing to document. The word 'current' usefully confirms that no user identifier is accepted and the caller's own identity is used, which is a small but genuine addition.

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 is essentially a restatement of the tool name and title ('Get user info'), though the word 'current' does add a real scope qualifier that distinguishes it from nextcloud_get_user_quota and nextcloud_get_properties. It does not say what 'info' includes or how it differs from the quota sibling, so an agent still has to infer the distinction.

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 guidance on when to call this versus nextcloud_get_user_quota or nextcloud_get_properties, both of which return user-adjacent data. No prerequisites or exclusions are stated; the agent must guess based on names alone.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds nothing beyond restating the title — no note on whether the quota reflects used vs. total bytes, how unlimited quotas appear, or whether it is cached.

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. It is efficient, though the brevity shades into under-specification rather than tightness.

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

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

There is no output schema, so the description bears responsibility for conveying what comes back — total vs. used vs. available bytes, units, or free-space semantics — and it says only 'storage quota information'. For a zero-argument tool that is the sole remaining gap, but it is an important one.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The only missed opportunity is confirming that the target user is implicit rather than selectable.

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 verb (get) and resource (storage quota information), but leaves the subject ambiguous: with zero parameters it presumably returns the authenticated user's quota, yet the description never says so, and it doesn't distinguish itself from nextcloud_get_user_info, which plausibly overlaps.

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

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

No guidance on when to call this versus nextcloud_get_user_info or any listing tool, and no preconditions or exclusions are stated. The agent must infer usage entirely from the name.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile completely. The description adds nothing beyond that—no mention of what an address book record contains, whether it can return private/shared books, or authentication requirements.

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

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

The description is a single short sentence with no filler, which is efficient. However, it is so terse that it is under-specified rather than genuinely concise—every word 'earns its place' only because there are so few 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?

There is no output schema, so the description carries the full burden of explaining what the agent will receive. It does not describe the return shape (e.g., book names, IDs, URIs, permissions) or whether the result is paginated, making it hard for an agent to know how to consume the output.

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 of 4 applies. There is no parameter semantics to add, and the description correctly avoids inventing unnecessary details.

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

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

The description 'List address books.' simply restates the tool name and title verbatim, offering no additional specificity. It does not clarify whether this lists personal address books, system-wide books, or how it relates to the sibling nextcloud_list_contacts.

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

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

No guidance is provided on when to use this tool versus alternatives. With 25 sibling tools including nextcloud_list_contacts and nextcloud_get_properties, an agent gets no hint about the relationship between address books and contacts, or whether this is a prerequisite step for contact operations.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: no indication of whether results are paginated, how many events are returned, whether recurring events are expanded, or what happens with an invalid calendar URL.

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 short sentence with no padding, so nothing is wasted. However, the brevity comes from under-specification rather than economy — the single sentence carries almost no actionable content.

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

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

No output schema exists, so the description bears responsibility for conveying what comes back, and it says nothing about the returned event structure. With an undocumented required parameter and no behavioral detail, the definition is not sufficient for an agent to call the tool confidently.

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 single required parameter calendar_url is undocumented everywhere. The description does not say whether it expects a full URL, a path, or a calendar ID, nor how to obtain one (e.g., via nextcloud_list_calendars) — a gap that directly risks malformed calls.

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 identifies the tool only by reference to another tool ('Alias for list_events'), rather than stating directly that it lists calendar events for a given calendar. Combined with the name and title the intent is inferable, but an agent reading the description alone gets a pointer instead of a verb+resource statement, and the aliasing relationship to the sibling nextcloud_list_events is implied rather than explained.

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?

'to support MCP server action' is internal jargon that gives no usage condition. It never says when to call this versus nextcloud_list_events or nextcloud_list_calendars, nor that calendar_url must identify an existing calendar.

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 readOnly, idempotent, non-destructive, and open-world, so the safety profile is fully covered. The description adds nothing beyond that – no note on scope (which calendars are 'available', primary vs shared), ordering, or what entries contain.

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 or redundancy, and the purpose is front-loaded. It is terse to the point of thinness, but nothing 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?

For a trivial zero-argument list tool, annotations plus name largely suffice, but with no output schema the description never says what a returned calendar looks like (identifier, name, access role), which is exactly what an agent needs to chain into event tools.

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; the absent-parameter baseline 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 clear verb+resource ('List ... calendars'), but the wording essentially restates the tool name and title. It does not distinguish this from calendar-adjacent siblings such as nextcloud_list_calendar_events or nextcloud_list_events.

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 indication of when to call this versus the event-listing siblings, nor any mention that it is the natural first step to discover calendar IDs before creating or listing events. The agent must infer usage from the name alone.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds essentially no behavioral context beyond restating the operation, such as pagination, return shape, or authentication 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?

The description is a single front-loaded sentence with no wasted words. It is efficient, though it is arguably too terse given the undocumented required URL parameter.

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

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

For a tool with one required, undocumented parameter and no output schema, the description leaves important context missing: how to obtain address_book_url and what the listing returns or how it is scoped. Annotations cover safety but not invocation completeness.

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 for the single required parameter. It only implies that an address book is involved and never explains the expected address_book_url format or where to get 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 description states a specific verb and resource: listing contacts within an address book. It clearly differs from siblings like nextcloud_list_address_books or nextcloud_create_contact, though it does not explicitly call out those distinctions.

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 'in address book': the agent knows it must target a specific address book, but there is no explicit guidance on when to use this versus nextcloud_list_address_books or how to obtain the required address_book_url.

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 readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds only the protocol name (PROPFIND), without explaining depth/recursion behavior, whether properties are returned, or how large listings are handled — the details an agent actually 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?

One short sentence, front-loaded with the verb and resource, with no filler. Brevity is appropriate here; the issue is missing content, not verbosity.

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

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

No output schema exists, so the description is the only place to learn what a listing returns, and it says nothing. Combined with an undocumented path parameter, an agent lacks the information needed to call this reliably against the right sibling.

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 `path` parameter, so the description must compensate and does not. It never says whether path is absolute or relative to the user root, what the empty-string default means, or what format (slash-prefixed, URL-encoded) is expected.

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 concrete verb and resource ("List files and folders in a directory"), so the purpose is understandable. But it never differentiates itself from the very similar sibling nextcloud_list_files, leaving an agent unable to pick between the two from the description 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 when-to-use, when-not-to-use, or named alternative is given. With siblings like nextcloud_list_files and nextcloud_get_properties in the catalog, the absence of routing guidance is a real gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint as false, so safety is covered. The description adds only 'returns basic info', a genuinely useful hint that the payload is abbreviated (there is no output schema), but it says nothing about pagination, result limits, or error behavior for an invalid calendar_url.

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, front-loaded sentence with no filler. It is efficient, though the terseness borders on under-specification rather than disciplined brevity.

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 and zero parameter documentation, the definition should at least explain the calendar_url format and how results are returned or bounded. With a confusingly similar sibling also present, the description leaves an agent without enough to call it confidently.

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

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

The schema has one required parameter at 0% description coverage, and the description does not compensate: it never says whether calendar_url is an absolute URL, a relative path, or an identifier, nor how to obtain one. This is exactly the case where the description must carry the load and does not.

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 events') and scopes it to a calendar, which is more than a restatement of the name. However, it offers no way to tell it apart from the near-identical sibling nextcloud_list_calendar_events, so an agent has no basis for choosing between 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as nextcloud_list_calendar_events or nextcloud_list_calendars. An agent facing both event-listing tools is left to guess.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds only the alias identity, not behavior: it says nothing about recursion, pagination, ordering, or what an empty path resolves to, and 'support MCP server action' is unexplained jargon.

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 a single short sentence with no waste in length, but half of it ('to support MCP server action') is filler that earns no place, and the useful part (alias relationship) is under-explained.

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

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

Given a real mutation-free but navigation-critical tool with a sibling duplicate and an undocumented parameter, the description leaves the two things an agent most needs unresolved: which tool to call and how to interpret path. Annotations cover safety but cannot fill these gaps.

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

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

With a single 'path' parameter at 0% schema description coverage, the description must carry the meaning and does not. It never explains whether path is absolute or relative, or that the empty default means the user's root folder, so the agent must guess.

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 does not state what the tool does; it only asserts that it is an alias for list_contents. An agent must infer the actual behavior (listing files in a directory) from the name and title alone, and the phrase 'to support MCP server action' adds no semantic content.

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 guidance on when to use this tool versus the near-identical sibling nextcloud_list_contents, which is exactly the ambiguity an alias creates. The agent is left to guess which of the two to invoke, with no stated preference, deprecation, or context difference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered; the description adds nothing further. It says nothing about whether results are paginated, what share types (user/group/link) are returned, or how large the listing may be for an open-world operation.

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

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

A single three-word sentence with zero waste and the resource front-loaded. It is arguably under-specified rather than bloated, which is penalized elsewhere.

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 tool with rich safety annotations and no output schema, the description is minimally adequate. An agent still lacks any signal about return shape, pagination, or share types, which matters for an open-world listing call.

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 and the schema is fully specified, so the baseline of 4 applies. The description's word "all" usefully signals that no filtering arguments 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?

"List all shares" states a specific verb and resource, which is clearly distinct from mutation siblings such as nextcloud_create_share and nextcloud_delete_share. It does not, however, differentiate itself from read siblings like nextcloud_list_contents or nextcloud_list_files, which in Nextcloud may also surface share information.

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 guidance on when to use this tool versus its many list siblings, and no mention of whether the listing is paginated, filtered, or scoped. The agent must infer everything about invocation context from the tool name alone.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, but the description adds nothing about behavior. Most importantly, the meaning of the 'overwrite' flag (whether an existing destination is silently replaced) is never disclosed, and destructiveHint=false could lead an agent to assume overwriting is safe. No return-value or error behavior is mentioned.

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 a single short, front-loaded sentence with no filler, so it is concise, but conciseness here comes at the cost of substance rather than being an efficient summary.

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

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

For a three-parameter mutation with no annotations beyond generic hints and no output schema, the description should carry the burden. Pointing to move_resource gives partial relief, but an agent still lacks the path semantics, overwrite behavior, and success/failure response needed to invoke it correctly.

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

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

Schema description coverage is 0% and the description supplies no parameter meaning at all. source_path, dest_path, and especially overwrite (default false) are completely undocumented, leaving the agent to guess whether paths are absolute, relative to a user root, or whether overwrite replaces or errors.

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

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

The description identifies the tool only by reference to a sibling ('Alias for move_resource'), so the actual verb+resource (moving a file/folder from source_path to dest_path) must be inferred from the other tool's name. It does distinguish this from siblings in the sense of declaring equivalence, but never states what the operation itself 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?

There is no guidance on when to call nextcloud_move_item versus nextcloud_move_resource, or versus nextcloud_copy_item / nextcloud_list_contents. Calling it an 'alias' actually leaves the agent unsure which of the two identical-sounding tools it should prefer.

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 disclose that this is not read-only and is open-world, so the description need not repeat safety basics. However, it adds almost no behavioral context: it does not explain the overwrite parameter, destination handling, error behavior, 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?

The description is a single front-loaded sentence with no wasted words. Its brevity is appropriate structurally, even though the missing detail is penalized in other dimensions.

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

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

For a mutation tool with three parameters, 0% schema coverage, no output schema, and an overwrite option, the description is too sparse. It provides the basic action but not enough context for an agent to call the tool confidently in edge cases.

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 three parameters, so the description must compensate, but it never mentions source_path, dest_path, or overwrite. The word 'move' implies a source and destination, but overwrite semantics and path expectations remain undocumented.

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 sentence states a clear verb and resource: 'Move a file or directory.' An agent can understand the core action, but the description does not distinguish this tool from the sibling nextcloud_move_item, leaving routing ambiguity between two similarly named move tools.

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

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

There is no guidance on when to use this tool versus alternatives, and no mention of the closely related nextcloud_move_item or copy tools. The agent must infer usage entirely from the name and 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not say what is returned (raw bytes, base64, text), how large files or binaries are handled, or what errors occur for a missing path or a directory. With annotations carrying the safety story, the remaining burden was return/content behavior, and it is unaddressed.

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 words are technically efficient and front-loaded with the verb, but the brevity here is under-specification rather than conciseness. A little more text on path format and return type would earn its place.

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

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

For a one-parameter read tool with rich annotations and no output schema, the description should at minimum pin down path semantics and what the caller receives. Neither is present, so an agent knows the intent but not how to call it correctly or consume the result.

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

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

The single required parameter 'path' has 0% schema description coverage, so the description must explain it and does not. It never says whether the path is absolute, relative to the user's root, whether a leading slash is required, whether directories are accepted, or how special characters are escaped.

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?

"Download a file" names a specific verb and resource, so the basic action is clear. However, it does nothing to distinguish this from siblings like nextcloud_list_files, nextcloud_get_properties, or nextcloud_write_file, leaving the agent to infer that this is the content-retrieval counterpart to the listing and writing tools.

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

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

There is no guidance on when to use this tool versus nextcloud_list_files (to discover paths) or nextcloud_get_properties (for metadata only). No prerequisites, no mention that a path must first be obtained, and no exclusions 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing on top of that: it does not disclose that the default overwrite=true will silently replace an existing file, nor the binary content handling implied by the anyOf 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?

It is brief, but the brevity is under-specification rather than conciseness. A single generic sentence with no front-loaded constraints fails to earn its place by conveying any 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 write/mutation tool with three parameters and no output schema, the description should at minimum explain overwrite behavior and content type handling. The annotations cover the safety profile, but the operational semantics an agent needs to call this correctly are absent.

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

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

Schema description coverage is 0%, so the description is the only place param meaning could be added, yet it mentions none of the three parameters. Path and content are largely self-explanatory by name, but the critical behavior of the optional overwrite flag (default true) is left entirely undisclosed.

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 ("Upload") and resource ("file") are present, so the basic operation is identifiable. However, it offers no differentiation from siblings like nextcloud_read_file, nextcloud_copy_resource, or nextcloud_move_item, and it never clarifies whether it creates new files or overwrites existing paths.

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 this tool versus alternatives, no prerequisites (authentication, target directory existence), and no exclusions. Usage can only be inferred from the name.

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