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

Annotations already declare readOnlyHint=false, openWorldHint=false, idempotentHint=false and destructiveHint=false. The description adds genuine context beyond that: it relies on a stored account connection (no credential parameters) and stays within a single host. It omits the most operationally relevant behavior, namely what happens if the folder already exists or if parent directories are missing.

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

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

Two short sentences with zero filler, and the most important scoping constraint is front-loaded. The second sentence is telegraphic but still earns its place by ruling out shares and cross-host behavior.

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

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

An output schema exists, so return values need not be explained, but the definition is thin for a mutation tool: existing-folder handling, parent-directory creation, and path syntax are all unaddressed. It is adequate to start a call and insufficient to predict 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 'path' parameter has 0% schema description coverage, so the description must compensate. It partially does by implying the path is relative to the workspace root, but gives no format guidance (leading slash, trailing slash, nested segments, whether intermediate folders are created).

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

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

States a specific verb and resource ('Create one folder') and pins down scope ('only inside the user's connected private Nextcloud workspace root'), which no sibling tool does. An agent can distinguish it from write_text_file or upload_file_base64 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 carves out what it will not do ('does not create public shares or contact another host'), which is useful boundary-setting, but never says when to prefer it or how to proceed if a file rather than a folder is needed. Usage is implied rather than stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is known; the description adds the non-obvious boundary facts (single item per call, root refused, confined to the connected workspace). It does not say whether deletion is permanent or moves to a trash/versions store, which is the one behavioral gap that matters for a destructive tool.

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

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

Two short sentences with zero waste; the primary scope constraint is front-loaded and the refusal rules follow as compact negative constraints. No restatement of the tool name or annotations.

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

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

For a one-parameter destructive tool with an output schema and full annotation coverage, the description covers enough to call it safely: scope, target confinement, and the root refusal. The remaining gaps (path format, permanence/trash behavior) are real but minor against the annotations and output schema.

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

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

Schema description coverage is 0% for the single `path` parameter, so the description must carry the load. It indirectly scopes the path to the user's private workspace root, which usefully rules out absolute URLs or other mounts, but never states whether the path is relative or absolute, leading-slash conventions, or whether folders are accepted.

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 a tightly scoped resource ("one item only inside the user's connected private Nextcloud workspace root"). It is unmistakably the only destructive single-item removal tool among the siblings, though it never names an alternative (e.g. move_file) for non-destructive relocation.

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

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

Gives concrete when-not conditions: deleting the root is refused, and other accounts/hosts/arbitrary URLs cannot be targeted. What's missing is positive routing guidance — nothing tells the agent to prefer move_file or a trash-based flow when the user may want to recover the item.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds meaningful behavioral context beyond annotations by disclosing the transfer size limit and clarifying that the destination is the stored account rather than an arbitrary 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?

The description is two short sentences, front-loads the core purpose, and includes only relevant constraints. There is no redundant filler.

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

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

The tool is simple and has an output schema, so return values need not be described. Still, the lack of any path-format guidance is a notable gap for a one-parameter tool with 0% schema description coverage.

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 only parameter, path, receives no explanation in the description. The description does not clarify whether the path is absolute, relative to the Nextcloud root, or expected in another format.

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: reading a small binary file from the user's private Nextcloud workspace as base64. It implicitly distinguishes itself from sibling read_text_file by specifying binary content, but it does not explicitly name alternatives.

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 useful constraints such as 'small' and 'enforces the transfer size limit,' implying when the tool is appropriate. However, it does not explicitly say when to use this versus read_text_file, get_file_info, or other file-related siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context by clarifying that the path is confined to the user's private workspace root and cannot reach another account, host, or public internet resource, though it does not discuss error cases or permission 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?

Two short sentences with the core action front-loaded and the security constraint immediately after. There is no filler and every sentence contributes useful scope 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?

The output schema handles return-value documentation, and annotations cover the read-only and closed-world safety profile. The description supplies the key path-scope constraint, though it could be more complete about path formatting and edge cases for a tool whose only parameter has no schema description.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaningful semantics for the path parameter by stating that it is relative and cannot escape the connected workspace root, but it does not specify formatting details, root-path behavior, or whether directories and files are both accepted.

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: read metadata for one item inside the user's connected private Nextcloud workspace root. This separates it from content-reading siblings such as read_text_file and download_file_base64, though it does not explicitly name those alternatives.

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

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

It gives a scope constraint about the path, but no explicit guidance on when to use this tool instead of list_files, search_files, read_text_file, or download_file_base64. The agent must infer the selection rule from the phrase 'metadata' 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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds real context beyond them: it uses only the connected account's stored server and permissions and touches no admin APIs or other hosts, which reinforces the closed-world scope.

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, and the scope caveat follows. Nothing here is filler.

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

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

An output schema exists, so return values need no explanation, and there are no parameters to document. The account-scoping and no-admin-API notes make the definition adequate for a simple read tool, with only the missing sibling routing as a 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?

The tool takes zero parameters, so per the baseline rule a 4 applies. The description correctly adds no parameter noise.

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 ('Read') and resource ('apps visible to the user's connected private Nextcloud account'), and scopes it to a single account. It implicitly separates itself from sibling file/share tools, though it never names an alternative for app-access questions.

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 'no administrator APIs or other hosts' line gives a useful boundary on what this will not reach. However, there is no explicit when-to-use statement or pointer to the sibling that answers a related question (e.g., get_nextcloud_capabilities).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful context by emphasizing that reads come only from the user's authenticated, connected server and that the destination is the stored account connection rather than an arbitrary 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?

Two short sentences, with the core action and source constraint front-loaded. The second sentence clarifies the destination constraint without repeating the first.

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

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

With annotations covering read-only/open-world behavior and an output schema covering return values, the description supplies the key missing context: authentication and connection scope. It could be slightly stronger by distinguishing this tool from related capability/app-access siblings.

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

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

The tool has zero parameters, so there is no parameter semantics burden for the description to carry. The baseline for a zero-parameter tool is 4.

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

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

The description states a specific verb and resource: reading capability hints from the authenticated, connected Nextcloud server. It distinguishes the source from an arbitrary URL or public web search, but does not differentiate this tool from sibling tools such as probe_native_nextcloud_mcp or get_nextcloud_app_accesses.

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 clear usage context and an explicit exclusion: use the stored authenticated account connection, not an arbitrary URL or public web search. It stops short of naming sibling alternatives or explaining when another tool should be preferred.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile and the 'no public web' constraint are partly redundant with structured data. The description does add real context — the listing is non-recursive and scoped to the authenticated user's own workspace root — but says nothing about ordering, pagination/limits, hidden files, or how large directories are handled.

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 and scope lead, and the constraint sentence follows. Nothing is repeated from the title or annotations verbatim.

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

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

For a single-optional-parameter read tool with an output schema (so return shape need not be described) and annotations covering safety and openness, the description supplies what remains: non-recursive listing and root-relative path scoping. Details like ordering and page limits are the only omissions and are minor at this complexity.

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 has no description, default-to-root explanation, or format guidance in the schema. The description partially compensates by stating paths are relative to the workspace root, but it never says what an empty/omitted path resolves to or whether a folder path requires a trailing slash.

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 direct children of the connected private Nextcloud workspace root — and pins the scope with 'direct children' (implying non-recursive) plus the explicit exclusion of other accounts, hosts, and the public web. It never names the sibling it is most easily confused with (search_files), so sibling differentiation is left implicit rather than stated.

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

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

Usage is implied by the scope statement: it is the tool for enumerating one directory of the private workspace. The 'cannot browse another account, host, or the public web' sentence functions as a when-not, but no alternative tool is named and there is no guidance on when to prefer search_files or get_file_info instead.

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

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

The annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds modestly by noting it uses the connected account's permissions and "never creates shares or publishes file content," but adds nothing about output shape, pagination, or what happens when the path is outside the workspace.

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 read-only scope constraint. No wasted text, though the second sentence duplicates annotation-covered safety facts rather than spending words on the undocumented parameters.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The remaining gap is the two undocumented parameters and the ambiguous empty-path default, which leaves the agent guessing on 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 0% and both parameters (path, include_subfiles) are bare titles with defaults, yet the description says nothing about either one. With a low-coverage schema the description is obligated to compensate, and it does not — notably it never explains what include_subfiles recurses over.

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 ("Read existing share metadata") and confines scope to "items inside the user's private workspace root," which is enough for an agent to distinguish it from the file-oriented siblings like list_files or search_files. It stops short of 5 because it never uses the word "list" to describe the enumeration behavior implied by the tool name.

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 a scoping constraint (private workspace root only) but no statement of when to call this versus alternatives, and no mention of prerequisites such as resolving a path first. Nothing tells the agent whether an empty path has special meaning.

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, non-idempotent, and closed-world, so the safety profile is known; the description adds a genuine constraint that both paths stay inside the same account and root. However, it omits the critical behavioral fact for a destructive tool: what happens when the destination already exists, and whether an existing file is silently clobbered, rejected, or gated by the overwrite flag.

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, and the core action leads. The second sentence earns its place as a scoping constraint, though it is slightly padded ("to another host or recipient") for a closed-world tool.

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

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

An output schema exists, so return values need not be described, and annotations cover safety. The remaining gap is meaningful for a destructive, non-idempotent mutation: the overwrite default of false and its consequences 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 0%, so the description carries the full burden, yet it never mentions the overwrite parameter at all, nor the path format (absolute vs. root-relative) or whether destination may be a directory. Only the vague notion of 'source' and 'both paths' is conveyed.

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

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

States a specific verb pair (move/rename) and the resource (an item) plus its scope (within the user's connected private Nextcloud workspace root). This is enough to distinguish it from siblings like delete_file, create_folder, or write_text_file, though it does not name an alternative 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?

Implicitly tells the agent when to use it (relocating or renaming an existing item) and adds a useful exclusion: no cross-host or cross-recipient transfers. It gives no guidance on when to prefer this over upload/download-style tools, nor on overwrite vs. fail-if-exists behavior.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false; the description reinforces this by stating discovery is done without invoking a native tool or contacting an unrelated destination, which is genuine added context about side effects. It stops short of describing failure behavior (e.g., whether unavailability surfaces as an error or a result field), though the output schema likely covers 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?

Two short sentences with the core scope front-loaded, no filler. The second sentence's phrase "unrelated destination" is slightly vague and could have been stated more directly, but overall it earns its space by clarifying what the probe does not touch.

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-argument, read-only probe with an output schema and full annotation coverage, the description supplies enough context to call it safely. The only meaningful gap is behavioral output on failure, which the output schema presumably handles.

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

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

The tool takes zero parameters, so the baseline is 4; the schema is empty and nothing in the description needs to explain inputs. The description correctly implies no arguments are required by tying the check to the already-stored account connection.

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 target: "Check MCP availability" scoped to "the user's stored Nextcloud account connection," which is more precise than a generic probe. The negative framing ("without invoking a native tool or contacting an unrelated destination") separates it from the sibling operation tools, but it never distinguishes itself from get_nextcloud_capabilities, which an agent could easily mistake for the same check.

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 "Check MCP availability only on the user's stored Nextcloud account connection" implies a pre-flight/verification use case, and the note about not invoking a native tool hints at when it is appropriate. However, there is no explicit when-to-use/when-not-to-use guidance and no naming of get_nextcloud_capabilities as the alternative for capability interrogation.

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

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

Goes meaningfully beyond the annotations (readOnlyHint=true, openWorldHint=false) by disclosing that content is bounded, that a transfer size limit is enforced, and that arbitrary URLs or files outside the root cannot be fetched. It does not say what happens on limit breach (truncation vs error), which is the remaining gap.

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

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

Two short sentences with the core scope front-loaded and the constraint second. No filler, though the phrasing is slightly compressed at the cost of precision on limits.

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?

Annotations cover the safety profile and an output schema exists, so return values needn't be explained; the description covers scope, size limits, and root confinement. The only meaningful omission is the exact path format and the truncation-vs-error behavior at the size limit.

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 required 'path' parameter, so the description must carry it; it only implies root-relative addressing without specifying format (leading slash, subdirectory syntax, encoding). Partial compensation, not full.

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

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

States a specific verb and resource ('Read bounded UTF-8 content') scoped to the user's private Nextcloud workspace root. It implicitly differentiates from download_file_base64 by specifying UTF-8 text rather than binary, though it never names a sibling 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 only implied: an agent can infer this is for text files inside the workspace root, not for binary downloads or searches. There is no explicit when-to-use/when-not statement or pointer to download_file_base64 versus this tool.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, openWorldHint=false; the description reinforces the closed-world profile ('bounded account search') and adds a genuinely new trait: only filenames are matched, not file contents, which tells the agent when to fall back to read_text_file. It does not mention depth or result-count bounding behavior, which limits it to a 4.

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 scope, with no filler. The second sentence is slightly redundant with the first for a reader who already knows Nextcloud, but it earns its place as a disambiguation cue.

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

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

An output schema exists so return values need no explanation, and the safety profile is covered by annotations. But with 4 undocumented parameters and no explanation of query matching semantics, an agent cannot confidently set path, max_depth, or max_results from this definition alone.

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

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

Schema description coverage is 0% across four parameters, so the description carries the full burden—yet it says nothing about what 'query' matches (substring, case sensitivity, globs), what 'path' scopes relative to the workspace root, or what max_depth and max_results control. Only the workspace-root scope is hinted at.

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

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

States a specific verb (search) and a specific resource and scope: filenames only, inside the user's connected private Nextcloud workspace root. It explicitly rules out public web search and other destinations, though it never distinguishes itself from the sibling list_files, which an agent could plausibly choose instead.

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 second sentence gives negative usage guidance—it is 'not public web search or a search of other destinations'—which narrows the context. However, there is no positive guidance on when to pick this over list_files or get_file_info, and no preconditions or exclusions relative to actual siblings.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description adds real value on top: strict base64 enforcement, size limits, the overwrite precondition, and the no-public-sharing restriction. It doesn't quantify 'small' or state what error occurs on failure, which keeps it below 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, with the core write action and scope front-loaded before the constraints. The fragments 'no public sharing' and the trailing clause are slightly terse/telegraphic but every sentence carries information.

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

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

An output schema exists, so return values need not be explained, and the description covers the key safety and precondition facts. The remaining gaps (the actual size limit behind 'small', path format) are minor but non-trivial for a zero-coverage 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 0%, so the description carries the full burden and does touch all three params – path (workspace root), content_base64 (strict base64), overwrite (required for existing files). However it never specifies path format, whether it's relative to the root, or the actual size cap, leaving meaningful gaps.

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 (write) and resource (small binary file) plus a clear scope limit (private Nextcloud workspace root). This implicitly separates it from write_text_file and download_file_base64, though it never names the siblings explicitly, so an agent must infer the division of labor from the type keywords.

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 one actionable rule – existing files require overwrite=true – and a constraint (no public sharing). But there is no explicit when-to-use versus the closely related write_text_file or create_folder, so the routing decision is only implied by 'binary' and 'workspace root'.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the meaningful extras: the overwrite prerequisite for existing files and explicit disclosure that no shares, messages, or publishing side effects occur. It omits error behavior when overwrite is false and the file 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 sentences, no filler, with the scope constraint front-loaded and the overwrite rule in the second position. The negative clause is compressed into a single line rather than expanded.

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

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

An output schema exists, so return values need not be described, and annotations carry the mutation risk profile. The description is nearly sufficient for correct invocation; the remaining hole is path semantics and failure behavior on a non-overwrite collision.

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

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

Schema description coverage is 0%, so the description must compensate. It correctly explains the non-obvious overwrite flag, which is the highest-value parameter detail. However, path (format, whether intermediate directories are created, relative vs absolute) and content (size or encoding limits) receive no added meaning, leaving two of three parameters 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?

Names a specific verb (write) and resource (text file) and pins the scope to the connected private Nextcloud workspace root, which is more than a restatement of the name. It does not explicitly distinguish itself from the sibling upload_file_base64, which is the closest alternative, so an agent must infer the UTF-8-text vs base64-binary split.

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

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

Gives clear applicability constraints: writes only within the private workspace root, and existing files require overwrite=true. The negative clauses ('Does not publish content, create shares, or send messages') usefully exclude adjacent behaviors, though no sibling is named as the alternative when the content is binary or outside the root.

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