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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description still adds real value by stating no content is downloaded, documenting the share-release restriction, and enumerating failure modes (path not released, malformed path, not found, auth/network errors). The 'permissions letters of the technical account' note is a useful caveat, though the description does not cover pagination or rate behavior, which is minor for a single-item metadata read.

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?

Well front-loaded: purpose, preference rule, then Parameters/Returns/Errors sections that make it scannable. The leading 'Levuvo Nextcloud MCP v0.5.3 - ' banner and the repeated 'Get file info' title restatement are wasted tokens, and the Returns list partly duplicates the output schema.

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

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

An output schema exists, so the returns list is a bonus rather than a requirement, and error semantics plus the path-rejection rules fill in everything else an agent needs to call this single-parameter read tool correctly. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaning beyond the schema by explaining that the path must be a configured share or lie below a shared folder. It restates the required-path fact, which is redundant, but the share-scoping constraint is genuinely extra information.

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

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

States a specific verb and resource (get the metadata of one shared file or folder) and immediately bounds it with 'without downloading its content', which cleanly separates it from read_file. An agent can pick between this and the sibling without opening a schema.

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

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

Explicitly names the alternative (read_file) and the exact condition that should route the agent here: when only type, size, modification date or permissions are needed. That is a concrete when-to-use rule rather than implied usage.

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

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

Goes well past the readOnly/idempotent annotations: it discloses the allowed-paths sandbox (never the whole account), the denied-paths exclusion, the 2000-entry folder rejection, the 250 limit with truncation flag, sort order, the permission letters of the technical account, and that no content is downloaded. Error conditions and their exact messages are enumerated.

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

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

Front-loaded with the action, then a well-ordered Parameters/Returns/Errors structure with no filler sentences. The only waste is the 'Levuvo Nextcloud MCP v0.5.3 - ' prefix, and the Returns section partially duplicates the existing output schema.

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

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

Given a read-only listing tool with four sibling tools and a 2000-entry guard, the description covers scope, recursion depth, ordering, truncation, exclusions, and failure modes. Return values are restated even though an output schema exists, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, yet the description still adds meaning: the empty path lists only configured shares and never the account root, a folder path lists exactly one level with folders first then by name, and limit drives the truncated flag. The malformed-path rejection rules (leading '/', '..', URL encoding) are additional operational guidance not spelled out in the schema.

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

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

States a specific verb and resource (list files / direct entries of a shared folder) and scopes it to configured Nextcloud shares. The error text explicitly routes file paths to sibling tools get_file_info or read_file, so an agent can separate it from read_file, get_file_info and search_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?

Gives clear usage context: 'Use it to navigate the shared folders step by step', and defines the default empty-path behavior versus a folder path (one level, non-recursive). It names alternatives only inside the error message for file paths and never says when search_files would be preferable, so it stops short of full when/when-not guidance.

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

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

Goes far beyond the annotations: file-size ceilings, 25M-character and 90-second extraction cutoffs, per-format extraction behavior (PDF text layer only, no OCR, encrypted PDFs rejected; DOCX body only; XLSX 200-sheet/200-column caps; RTF flattened), the guarantee that macros/scripts/embedded objects are never executed, etag mismatch failure, and a full error catalogue including folder paths, unshared paths and malformed paths. It also flags the returned content as untrusted data, which is behaviorally important and absent from annotations.

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

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

The content largely earns its place, but it is one undifferentiated block: format support, limits, parameters, return fields and errors all run together in a single paragraph. The 25000000-byte limit is stated three separate times and the version/server banner plus "Read-only" duplicate metadata available 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 paging, multi-format extraction tool this is essentially complete — limits, per-format caveats, pagination contract, error strings and injection warning are all covered, and the return shape is documented in prose as well as in the output schema.

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

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

Schema coverage is 100%, so ranges and defaults are already documented; the description's added value is the loop semantics connecting offset, max_chars, next_offset, has_more and etag, plus the requirement that path be a file rather than a folder. It still restates defaults and bounds that duplicate the schema, so it is not fully additive.

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 file") and immediately scopes what is returned: a section of the extracted text of one shared file. It explicitly distinguishes itself from the closest sibling ("for metadata use get_file_info"), so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use rule ("only when the actual content is required") with the named alternative, and adds a concrete multi-call protocol: if has_more is true, call again with offset=next_offset and the returned etag until has_more is false. It even warns against drawing conclusions from a partial section.

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

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

Beyond the readOnly/idempotent annotations, it discloses the real operating envelope: depth, directory and result caps, parity with server defaults, that up to 100 folders are scanned with 4 parallel requests, that denied paths are never searched or returned, and that complete=false can hide hits for three named reasons. It also enumerates concrete error strings for file-as-path, unshared paths, malformed paths and missing entries, which is exactly the kind of behavior an agent cannot infer from structured fields.

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

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

Purpose is front-loaded but preceded by a version string and a triple statement of the same limits (configured values, then server defaults, then the env var names). It also narrates the full return shape even though an output schema exists, and repeats parameter ranges verbatim, so several sentences do not earn their place.

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

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

For a bounded filesystem search with a real truncation model, it covers starting scope, matching rules, all caps, exclusion policy, completeness signaling and failure modes. An agent can call it correctly, interpret partial results, and know when to retry with different arguments.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: matching is case-insensitive substring, the shared roots themselves are candidates when path is empty, and max_depth counts levels below the starting folders. It does, however, largely restate the same parameter ranges and defaults that already appear in the schema.

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

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

It states a specific verb and resource ('Search file names', 'Find files and folders by NAME') and sharply scopes it against the bigger space of search ('no full-text search inside documents'). It only differentiates from siblings reactively, inside an error message ('Use get_file_info or read_file'), rather than stating up front how it relates to list_files or get_file_info.

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 context: name-only matching, shared areas only, behavior with and without path, and an explicit next action when results are incomplete ('raise max_depth or max_results, narrow the query or search a subfolder with path'). It does not proactively name list_files as the alternative when the agent just wants to enumerate a folder.

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