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

Goes well past the annotations: all-or-nothing validation ('If any source is missing, nothing is copied'), partial-success semantics under overwrite=false (skipped items are listed), and long-running behavior returning a handle for file_task. The description refines destructiveHint=true rather than fighting it — the default path destroys nothing.

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

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

Five tight sentences, each carrying distinct operational information, with the core purpose and the move_files routing front-loaded. No filler and no restatement of the name.

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

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

No output schema exists, and the description covers the return path (handle for file_task) plus batch outcomes (skipped-and-listed), so nothing an agent needs in order to call or follow up 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%, so the baseline is 3; the description earns above that by explaining the consequence of overwrite's default ('items already at the destination are skipped and listed') and by reinforcing the existence precondition on dest_folder, which the schema only implies.

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

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

States a specific verb and resource (copy files or folders into a destination folder) and pins the semantics that distinguish it from move: 'the sources stay in place' and folders copy recursively.

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 ('To move instead, use move_files') and adds preconditions to use: 'dest_folder must already exist; it isn't created.' It also explains what happens under each overwrite mode, so the agent knows which call shape suits which intent.

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?

Adds substantial context beyond the destructiveHint=true annotation: the async timeout behavior, that the operation keeps running server-side after the reply, that a handle is returned for photo_task, and that overwrite replaces existing destination files. These are exactly the behavioral traits an agent needs to reason about a long-running destructive write.

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 tightly packed sentences with no filler; the destructive overwrite behavior is stated at the end and the timeout/handle behavior is front-loaded where an agent will see it before calling.

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 still tells the agent that a handle for photo_task may be returned for long copies, covering the key return-value concern. It leaves some ambiguity about the reply's structure in the synchronous case but is otherwise sufficient for a 6-parameter rewrite tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by explaining the on_conflict=overwrite consequence and the same-space/cross-space semantics of space vs dest_space. It does not add syntax or format details for ids/folders/destination beyond what the schema already documents.

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 (Synology Photos items and/or whole folders), plus the scope of copying into another folder within or across spaces. This clearly distinguishes it from move_photos and copy_files, which act on different resource types or semantics.

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 clear operating context: it blocks up to a task timeout (30 s by default), longer copies continue on the NAS with a handle for photo_task, and on_conflict=overwrite replaces destination files. It does not explicitly name when to prefer move_photos or copy_files, but the copy-vs-move distinction and cross-space capability are clear.

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

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

With annotations declaring readOnlyHint=false/destructiveHint=false, the description adds substantial context: destination must already exist (DS won't create it), omitting it falls back to default, non-managers must set a default first, and task IDs are returned only in certain cases (not for credentialed URLs). Rich disclosure beyond 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?

Front-loads purpose then constraints. Dense but every clause (folder prerequisite, default fallback, ID-return caveat) carries real information, though the parenthetical nesting is slightly heavy.

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, it covers the key operational facts an agent needs: source precedence, destination requirements, and return-value conditions. Nothing essential 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%, but the description still adds meaning: destination is share-relative and must be existing, and the default-destination behavior with the non-manager caveat. Goes beyond the schema on the most consequential parameter.

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

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

States a specific verb ('Create') and resource ('download tasks') with the two supported source types (URIs or local .torrent/.nzb file). Clearly distinguishable from siblings like delete_download, list_downloads, or edit_download.

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?

Explains the destination prerequisite and routes to create_folder or set_download_config when a folder or default destination is missing. Clear context for use, though it doesn't explicitly contrast with sibling task-creation flows, so not a full 5.

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

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

Annotations already disclose non-read-only, idempotent, and non-destructive behavior. The description adds useful context: paths must start from the shared folder root, missing parents are created by default, and existing folders are not an error (reinforcing idempotency). It does not cover permissions or return behavior, but adds meaningful traits beyond annotations.

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

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

Two tightly written sentences with zero waste. The path format constraint is front-loaded and the default behavior is explained immediately after.

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

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

For a two-parameter creation tool with full schema coverage and safety annotations, the description covers path format, parent creation, and idempotency. Return values are not described, but no output schema exists; the only minor gap is not stating permission requirements.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema. The description adds an example path and clarifies the default effect of force_parent, but largely mirrors what the schema already states.

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

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

States a specific verb and resource ('Create one or more folders') and immediately clarifies the input format with a full-path example. No sibling tool offers folder creation, and the scope (batch, shared-folder paths) is unambiguous.

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

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

Usage is implied by the clear purpose and path requirement, but the description never says when to use this versus alternatives (e.g., relying on upload_file's implicit parent creation). It also provides no explicit when-not guidance.

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

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

Annotations mark it destructive, and the description adds substantial behavioral detail beyond that: source URLs are lost, finished task files are retained, unfinished partial data is discarded irreversibly, and force_complete should not be relied on. This is exactly the kind of destructive-operation disclosure an agent needs.

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

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

Three tightly written sentences, with the core action front-loaded and the irreversible consequences and confirmation requirement following immediately. No filler.

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

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

For a destructive, parameter-light tool with no output schema, the description covers the essential risk profile, file-retention behavior, confirmation requirement, and force_complete caveat. Nothing needed to call it safely appears 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 task_ids and force_complete are already documented in the input schema. The description reinforces the force_complete caveat but does not add much semantic detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb and resource: removing download tasks. It also clarifies that finished task files are kept, which helps distinguish it from a file-deletion sibling, but it does not explicitly name alternatives such as delete_files or pause_download.

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: deletion is permanent and requires naming tasks and confirming with the user before proceeding. It does not explicitly compare when to use this instead of pausing, editing, or deleting files, so it falls short of full alternatives guidance.

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

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

Annotations already mark this as destructive, and the description adds substantial context: recycle-bin routing, permanent deletion inside a bin, recursive default behavior, all-or-nothing path handling, and an async handle for long deletes. These details go well beyond the annotations without contradicting them.

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 action and recursive behavior are front-loaded, and each subsequent sentence adds a distinct operational fact needed for a destructive tool. There is minor overlap with the schema on exact paths and recursive behavior, but no filler.

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

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

For a destructive tool with annotations but no output schema, the description covers the essential behavior an agent needs: recycle bin versus permanent deletion, recursive folder handling, atomicity when paths are missing, and async handling for long operations. Nothing critical is omitted.

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

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

Schema description coverage is 100%, so the schema already documents exact paths and the recursive default/refusal behavior. The description reinforces those points but adds little parameter-specific syntax or meaning beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource ('Delete files or folders') and immediately distinguishes the recursive folder behavior. It is clearly distinct from siblings such as delete_download and file_task.

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 explains the conditions that determine whether a deletion is recyclable or permanent, notes that paths are exact and that any missing path aborts the whole delete, and points to list_recycle_bin, restore_from_recycle_bin, and file_task. It does not explicitly say when to prefer delete_files over delete_download, but the operational context is clear.

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, but the description goes further by disclosing exactly what survives (the photos stay in place) versus what is unrecoverable (selections, conditions, share links) and requiring user confirmation beforehand. That is precisely the missing behavioral context a destructive tool 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?

Three short sentences, front-loaded with the destructive action and the survivability caveat, then confirmation, then alternatives. No sentence is filler and the ordering matches how an agent should reason about the call.

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 annotations covering safety and no output schema, the description supplies everything else an agent needs: what is destroyed, what remains, irreversibility, confirmation requirement, and sibling routing. 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% and the schema itself already explains the ID-or-name input and the ambiguous-name behavior, so the description carries no additional parameter burden. It says nothing about the 'albums' argument beyond what the schema documents, so the baseline 3 applies.

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

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

Specific verb + resource ('Delete Synology Photos albums') with the scope of what is deleted made explicit (album objects plus their share links, normal or smart). It also names the two nearest siblings it is not — photo_album action=remove and delete_photos — so an agent can separate it from them without reading 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?

Explicitly states when not to use it ('To only take items out of an album, use photo_album action=remove; to delete the photos themselves, delete_photos') and adds a procedural gate ('Confirm with the user first'). The routing conditions are fully specified.

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 destructiveHint=true by explaining recycle-bin semantics (and the permanence fallback when no recycle bin exists) and the async pattern where a large delete keeps running on the NAS and returns a handle for photo_task. These are exactly the consequences an agent needs before invoking a destructive 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?

Four short sentences, each carrying new information: what gets deleted, where it goes, what happens on big deletes, and the confirmation requirement. The destruction scope is front-loaded so nothing important is buried.

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

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

No output schema exists, and the description compensates by explaining that the reply returns a task handle for photo_task. It leaves out permission/auth requirements and partial-failure behavior on a multi-folder delete (up to 1,000 IDs), which would matter for a destructive bulk operation.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns the extra point by clarifying that deletion is recursive over the folders argument and by giving the 'gone, not recycled' caveat that conditions how the space parameter's behavior plays out.

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

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

Names a specific verb (Delete) and resource (folders in Synology Photos) and states the recursive scope ('everything in them (files and subfolders)'), which immediately distinguishes it from delete_photos and delete_photo_albums in the sibling list.

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

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

Gives an explicit operational guardrail ('Confirm with the user first') and implies the space-scoped context, but never explicitly routes an agent to delete_photos for individual files or names when not to use this tool — the disambiguation is inferable from the sibling names 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?

Goes well beyond the destructiveHint=true annotation: it discloses recycle-bin placement, the case where items are permanently unrecoverable ('otherwise they're gone'), and that a large delete runs asynchronously returning a handle for photo_task. This is exactly the safety/async context annotations cannot convey.

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

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

Front-loads the core action and scope, then layers destructiveness, async behavior, and the alternative in tight sentences. Every sentence earns its place with no redundancy.

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

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

For a destructive two-param mutation with no output schema, it covers safety (recycle bin vs. permanent), async result handling (photo_task handle), confirmation, and the nearest alternative. Nothing an agent needs for correct invocation is missing.

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

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

Schema coverage is 100%, so both `ids` and `space` are fully documented in the schema. The description adds only 'by id' and 'the files themselves', which the schema already implies; baseline 3 applies when schema does the heavy lifting.

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

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

States a specific verb and resource ('Delete Synology Photos items (the files themselves) by id') and immediately disambiguates from album removal via 'photo_album remove'. An agent can distinguish it from delete_photo_folders, delete_photo_albums, and delete_files without opening 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?

Gives an explicit alternative ('To only take items out of an album, use photo_album remove') and a prerequisite ('Confirm with the user first'). It doesn't address all sibling confusions (delete_photo_folders, delete_files) or the space-scoping choice, but the highest-risk alternative is covered.

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 the description earns credit by explaining exactly what gets destroyed and when: an existing local file is kept and the call fails unless `overwrite` is true. It doesn't cover other behavior an agent might need, such as whether the call blocks until the transfer completes or what is returned (no output schema 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?

Three tight sentences: the core action first, then folder/zip semantics and the shared-folder restriction, then the overwrite caveat. No padding.

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

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

For a 4-parameter tool with no output schema, the description covers the destructive path and the notable edge cases well. It leaves out the return value (presumably the saved local path) and any indication of long-running/large-transfer behavior, which matters for a NAS download.

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 `filename`, `overwrite`, `dest_folder` and `path` are all documented in the schema already. The description restates the overwrite default and the zip naming rule but adds no semantics beyond the schema — baseline 3 is appropriate.

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

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

States a specific verb and resource plus the destination ('Download a NAS file to a folder on this machine (where this server runs)'), which separates it from the download-station style siblings like create_download. It also defines the scope precisely: a folder becomes a ZIP, a whole shared folder is not allowed.

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 concrete conditions that govern use — folder downloads produce `<folder>.zip`, shared folders can't be downloaded, and existing local files block the call unless `overwrite` is set. It never explicitly names an alternative sibling (e.g. create_download) or when not to use this tool, so it stops short of full routing guidance.

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

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

Annotations declare destructiveHint=true, and the description usefully narrows that: writes are confined to allowed local folders and existing files are preserved unless overwrite=true. That scoping context goes beyond the annotations. It doesn't cover failure modes for missing IDs or partial batches, which would be the next layer.

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

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

Three tight sentences, front-loaded with verb, resource, and destination, then behavior, then the sibling escape hatch. No filler.

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

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

With no output schema, the description adequately characterizes the result (one file per item, named after the original, previews suffixed). It stops short of describing return values or progress reporting, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds the naming convention ('one file per item, named after the original') that the schema does not state, and reinforces the overwrite-skip semantics. The size and space parameters' meanings are left entirely to the schema.

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

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

States a specific verb (download) and resource (Synology Photos items by id) plus the destination (a local folder) and the output form (original files or JPEG previews, one file per item, named after the original). It also explicitly distinguishes itself from download_file in a sibling module.

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 alternative route — use File Station's download_file for files outside Photos when that module is enabled — which is a clear when-to-use rule. It doesn't address when to prefer copy_photos or when to pick previews over originals in prose, but the core routing guidance is present.

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

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

Annotations already mark this as a non-read-only, idempotent, destructive mutation. The description adds valuable behavior beyond annotations: API version requirements, scope limited to listed tasks, and the fact that finished tasks are not moved and report `not changed`.

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

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

Four tightly written sentences, front-loaded with purpose and scope, then prerequisites, alternatives, and edge-case behavior. No filler.

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

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

Given the tool’s complexity as a mutation with no output schema, the description covers the essential context: what can be edited, API compatibility, task scoping, the global-settings alternative, and finished-task behavior. An agent can call it correctly from this.

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

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

Schema description coverage is 100%, so the schema already documents task_ids and destination thoroughly. The description reinforces that destination is the only editable field, but adds little syntax or format detail beyond the schema.

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

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

States a specific verb and resource (edit task parameters) and names the only currently supported editable field, destination. It also distinguishes the tool from the sibling set_download_config, which handles global settings.

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 says to use set_download_config for global settings and edit_download only for listed tasks. It also gives the prerequisite of a newer Download Station with Task API v2 and notes the clear error on older versions.

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 and destructiveHint=true, so the safety profile is covered by structured data. The description adds value by framing the target as a face-recognition group, but it never explains which of the listed actions is destructive or whether effects are reversible (e.g. does renaming overwrite an existing name, does hiding persist). Given the destructive flag, a note on irreversibility would have earned a 4-5.

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

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

Two sentences, front-loaded with the core verb and resource, followed by the enumeration and the alternative. Nothing is wasted and no sentence repeats the schema.

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

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

For a 5-parameter mutation tool whose parameters are fully documented and which has no output schema, the description covers purpose, the operation set and the one obvious sibling. The remaining gap is behavioral: a destructive mutation tool with no output schema should say what the caller gets back or what gets lost, so it falls just short of complete.

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

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

Schema description coverage is 100%, so every parameter (name, space, action, person, item_id) is already documented in the schema, including the `""` unnamed convention and the include_hidden caveat. The description only echoes the action list, adding no syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Change one person ... in Synology Photos'), clarifies the domain concept ('a face-recognition group'), and enumerates the concrete operations (rename, hide/unhide, set cover). It also names the sibling merge_people, so an agent can separate 'edit one' from 'combine two' without opening either schema.

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

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

Explicitly routes the agent to merge_people when the task is combining duplicate groups, which is the main confusion risk in this domain. It stops short of naming the other adjacent operations (listing people via list_photo_collections, deleting a person) as out of scope, so the exclusion set is not fully closed.

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, but the description adds context the annotations cannot: edits are written into the original files, so file dates and sizes change, and favorite requires Photos 1.9.1+. It also documents repeat-behavior for rotate and shift_hours. That is substantive added value beyond the 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?

Three tight sentences with zero filler. The editable-field list, the mutation warning, and the routing to tag_photos are front-loaded in that order, so the most decision-relevant information comes 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?

For a destructive, multi-parameter mutation tool with no output schema, the description covers what changes, what is irreversible (original files modified), what is out of scope, and where to go for tags. Nothing an agent needs before calling is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by stating cross-parameter semantics the schema can only partially convey: fields apply uniformly to every id, and taken_time vs shift_hours are mutually exclusive alternatives. It stops short of explaining the space/id coupling, which the schema handles alone.

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 ('Edit Synology Photos items') and enumerates exactly which attributes are editable (rating, description, taken time, rotation, favorite). It also names the sibling tag_photos and explicitly excludes location, so an agent can distinguish it from neighboring photo tools without opening any schema.

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

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

Gives concrete invocation guidance: 'Pass only the fields to change; they apply to every id given,' plus explicit exclusions — location can't be edited and tags must go through tag_photos. That is when-to-use, how-to-use, and when-to-use-something-else in one short block.

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?

Adds substantial context beyond the annotations: the NAS keeps working after the reply, stop may leave the operation partly done (consistent with destructiveHint=true), status may return the final result only if DSM still has it, and handles are scoped to the same NAS user. These are real behavioral constraints an agent cannot get from readOnlyHint/destructiveHint.

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

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

Front-loads the purpose, then the handle/no-handle cases, then the caveats. Every sentence carries a distinct piece of information, and the closing polling warning is the right thing to end on.

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 supplies what the agent needs about return behavior: status shows progress or the final result, stop may leave partial state, and no-handle returns the user's running operations. Nothing material is missing for a two-parameter follow-up tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns more by explaining what each action yields (progress versus final result; stop with possible partial completion) and what omitting the handle does. The only gap is that it doesn't specify handle format beyond the example prefix.

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 action (follow up on a running delete/copy/move/restore) and the resource (NAS file operations), and explicitly ties itself to the sibling tools that produce the handles. An agent can distinguish this from delete_files/copy_files/move_files without opening any schema.

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

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

Gives explicit branching: with a handle use action=status or action=stop; without a handle it lists the user's running operations, which is called out as useful in a new chat or after a restart. It also names an anti-pattern (don't poll in a loop) and the condition that should trigger a check 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?

Annotations only declare read-only/non-destructive; the description adds genuinely non-obvious behavior: permission-scoped counting with silent omission of unreadable subfolders, runtime that can reach minutes on large trees, and a 120 s timeout that aborts the call. These are exactly the operational facts an agent needs before invoking it.

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

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

Four sentences in priority order: what it computes, when to reach for it, the permission caveat, then the performance/timeout caveat. No repetition of the schema or the annotations.

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

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

No output schema exists, so the description compensates by naming the three returned metrics, and it also covers the two failure modes an agent must anticipate (unreadable subfolders, timeout). Nothing material is left undefined for a one-parameter read tool.

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

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

There is a single required parameter and schema coverage is 100%, with the schema already supplying an example path, so the schema carries the load. The description adds no format, path-relative, or permission detail about the argument beyond what is structured, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Calculate the total size of a folder') and enumerates the three values returned (total size, file count, folder count), which separates it from get_file_info and list_files. The scope 'including everything below it' makes the recursive nature explicit.

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 frames the trigger question ('how much space does X use'), giving a clear context for selection. It does not name a sibling alternative or an exclusion (e.g., use get_file_info for a single file's size), so it falls short of a full when/when-not routing statement.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: non-manager accounts get a per-user view labeled as such rather than NAS-wide settings — an important output-shape caveat an agent could not 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?

Three short sentences, each carrying distinct information: what is returned, the permission-dependent view caveat, and the sibling alternative. Nothing is repeated from the schema 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?

With no output schema, the description usefully names the configuration categories returned, and the per-user caveat covers the main behavioral surprise. It could say slightly more about the shape of the speed values, but for a no-argument read tool this is close to complete.

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

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

The tool takes zero parameters, so there is no parameter meaning for the description to supply; baseline 4 applies. The description does not need to compensate for any 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?

States a specific verb (Get) and resource (Download Station global configuration) and enumerates the exact fields returned: default destination, BT/HTTP/FTP/NZB/eMule max speeds, eMule and auto-unzip state. This clearly separates it from sibling config tools like get_schedule and set_download_config.

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?

"Use get_schedule for the weekly plan" gives an explicit alternative and the condition that selects it. It does not mention set_download_config for modifying these same settings, which is the nearest sibling and a likely confusion point, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true/destructiveHint=false, so safety is covered. The description adds non-obvious behavioral context: which data blocks are included and the conditional availability of files/trackers/peers (BT only), which prevents an agent from assuming empty results mean failure. It doesn't mention whether trackers/peers can be slow or omitted for non-BT tasks beyond the '(BT only)' note, but that gap is minor.

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 dense sentence enumerating return contents, followed by two short routing sentences. Zero filler and front-loaded with the purpose before the sibling disambiguation.

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 compensates well by listing exactly what the response contains. For a single-parameter read-only lookup with annotations covering the safety profile, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already specifies task_id format (`dbid_…`) and its source. The description restates the source ('Use list_downloads first') without adding syntax or validation detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource (retrieve detailed info for a specific download task) and enumerates the four information blocks returned (detail, transfer, files, trackers, peers). Clearly distinguishes itself from get_download_stats and get_download_config by naming both siblings.

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

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

Explicit sequencing ('Use list_downloads first to find the task_id') plus explicit routing rules for alternatives: totals → get_download_stats, settings → get_download_config. Nothing is left to inference for an agent picking among the three get_* download tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful behavioral detail that eMule figures appear only when the eMule service is enabled, but says nothing about whether the values are instantaneous samples, cumulative averages, or what units they're in.

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

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

Two sentences, zero waste, with the returned metrics front-loaded and the sibling routing placed last where it belongs as a disambiguation clause.

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-param read tool with no output schema, the description covers what comes back (total down/up plus conditional eMule speeds) which is the main thing an agent needs. The missing piece is units/sampling semantics of the returned numbers, but the shape of the response is adequately conveyed.

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?

Zero parameters, so the schema carries no semantics burden and there is nothing for the description to compensate for. Baseline 4 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?

Uses a specific verb (get) and resource (Download Station throughput statistics) and spells out exactly which metrics are returned: aggregate download/upload speed plus conditional eMule speeds. It also distinguishes the aggregate scope from the per-task view in list_downloads, so an agent can tell it apart from siblings.

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

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

Explicitly routes the agent: use this for aggregate throughput, use list_downloads for per-task speeds. Clear usage context, though it doesn't address other plausibly adjacent siblings such as get_download_info or get_resource_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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond that: the error case for missing paths and a preview of the returned fields. It stops short of saying how multiple paths are handled on partial failure or any batching limits, which keeps it below 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 tight sentences with the core purpose front-loaded, followed by the sibling disambiguation and error behavior. Every sentence carries distinct information.

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

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

With no output schema, the description usefully names the returned metadata fields and the not-found behavior, making it callable without opening the schema. It could say a bit more about multi-path results or limits, but nothing critical 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 both `paths` and `additional` (field list, defaults, rejected unknown values) are fully documented in the schema. The description only restates example fields like 'real path on the volume' and 'permissions' rather than adding syntax or format details, so the baseline 3 applies.

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

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

States a specific verb and resource — retrieving detailed metadata for files/folders at known paths — and enumerates what metadata (size, owner, timestamps, permissions, real path). It explicitly distinguishes itself from list_files and get_dir_size by naming those siblings.

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

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

Gives an explicit precondition ('whose paths you know') and routes the agent to the correct alternatives: list_files for folder contents and get_dir_size for a folder's total size. It also sets expectations for a non-existent path being reported as not found.

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 this a safe read (readOnlyHint=true, destructiveHint=false), so the lower bar applies. The description adds real value beyond that: it discloses the full return field set, that EXIF requires an explicit flag, and that nonexistent IDs are surfaced as 'not found' rather than erroring out. It does not mention permissions or space-boundary behavior, which keeps it from a 5.

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

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

Three tight sentences: what it returns first, the routing hint second, the not-found edge case last. No filler, and the most decision-relevant information (the detail payload vs. list_photos) is front-loaded.

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, yet the description enumerates the returned fields comprehensively (filename, folder, taken time, size, resolution, rating, favorite, description, tags, people, GPS, camera, EXIF), so an agent knows what it will get. The not-found handling covers the main surprising edge case for an ID-based lookup.

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

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

Schema description coverage is 100%, so the schema already documents ids (1-20 from list_photos), exif, and space. The description's 'full EXIF table with exif=true' restates the schema rather than adding syntax or constraints, and it never explains the personal/shared space semantics. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Get full details for Synology Photos items by id') and then enumerates exactly which fields are returned, including the opt-in EXIF table. An agent can distinguish this from list_photos or get_file_info without opening any 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 and the condition that selects it: 'Use it when list_photos' one-line rows aren't enough,' and notes IDs come from list_photos. It stops short of stating when NOT to use it (e.g. bulk retrieval vs. the download/copy photo tools), so it is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: it requires a DSM administrator account and other accounts receive permission_denied, plus it flags the data as live. It doesn't discuss sampling windows or response shape, so not a 5.

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

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

Three short sentences, front-loaded with the resource and metrics, then auth constraint, then the disambiguation pointer. Every sentence carries distinct information with no repetition.

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

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

For a parameterless read-only tool with annotations covering safety and no output schema, the description supplies everything an agent needs: what it returns, the auth prerequisite and failure mode, when to call it, and which sibling to use for adjacent data.

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 the description needs to disambiguate; baseline for zero-param tools applies. Nothing in the description contradicts the empty 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 (get live resource utilization) and enumerates the metrics returned: CPU load, memory, disk I/O, network throughput. It also explicitly separates itself from the sibling get_system_info by naming what that tool covers 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?

Gives an explicit use case ('check if the NAS is under heavy load before starting expensive work on it') and routes the agent elsewhere for model/firmware/temperature/uptime. No inference required.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds the important behavioral nuance that output degrades to flags-only without admin rights. It does not describe pagination or any rate/size considerations, but for a zero-parameter read that is minor.

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

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

Two sentences, zero waste. The returned content is front-loaded and the permission caveat follows as a qualifier, which is the right order for an agent scanning for what it will get back.

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 and no parameters, the description carries the entire burden of explaining the return value, and it does so concretely: named fields plus the shape and domain of the weekly grid. Nothing an agent needs in order to call this 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?

The tool takes no parameters, which is the baseline-4 case; there is nothing for the description to clarify. The description correctly implies no input is needed by framing the call purely in terms of what is returned.

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 ('Get') and resource ('Download Station schedule') and then enumerates exactly what the response contains: enabled flag, limited-speed rates, and a 7-day × 24-hour weekly plan with three state values. This is clearly the read counterpart to the sibling set_schedule, so an agent can distinguish them 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?

It gives a clear usage condition: retrieving the weekly plan requires a Download Station manager/admin account, and without one only the flags are returned. That is a real prerequisite rather than generic filler, though it never explicitly names set_schedule as the mutation alternative or states when not to call it.

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

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

Goes well past the readOnlyHint/destructiveHint annotations by disclosing that the response is account-dependent: admins get CPU, time zone, NTP, firmware, update/crash flags, eSATA, redundancy, while 'any other account gets a line saying so'. It also conditions fields on hardware ('the temperature where the NAS has a sensor') and DSM version ('on DSM 7.2.2 and later'), which is exactly the behavioral context an agent cannot infer.

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 a one-line summary, then the conditional detail, then the routing pointer to the sibling — a sound structure. The middle sentence is a long comma-separated field inventory, which is dense but earns its place given there is no output schema; some of that enumeration could be tightened.

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 must carry return-value information — and it does, covering both the always-present fields and the admin-only conditional fields, including the fallback line for non-admins. Combined with the sibling pointer and account-dependence caveat, nothing an agent needs to call this 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-arg tool applies. The description correctly spends no words on inputs and puts the budget into output shape instead.

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?

Specific verb+resource ('Get everything DSM reports about the NAS') with an explicit enumeration of the resource's contents. It also names the sibling it must not be confused with (get_resource_usage), so an agent can separate the two 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?

Explicit when-to-use ('identify the NAS, check its basic health or tell the time on it') plus a named alternative with the selecting condition ('For live CPU, memory, disk and network load, use get_resource_usage'). Both sides of the routing decision 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 establish readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context beyond that: paged output with a footer total, filter/sort covering the whole queue, and permission-scoped visibility for non-managers. The caveat that an empty list may reflect permissions rather than NAS idleness is especially useful.

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

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

The description is front-loaded with the core purpose, then adds return shape, pagination, cross-page filtering semantics, and the permission caveat in a compact set of sentences. Every sentence contributes specific operational value.

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, but the description explains the return columns, footer behavior, and permission-scoped results. Combined with the read-only annotations and fully documented parameters, an agent has enough information to call this 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 100%, so the baseline is 3. The description adds cross-parameter meaning beyond the schema, notably that sort/filter operate across the full queue and that sort_by=completed with limit=1 returns the most recently finished task.

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

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

The description states a specific verb and resource: list download tasks in the Download Station queue. It also immediately frames the result as a tabular summary, which distinguishes it from sibling tools like get_download_info and get_download_stats that focus on detail or aggregates.

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 clear usage context for pagination, status filtering, and sorting, including a concrete example of using sort_by=completed with limit=1 to find the latest finished task. It does not explicitly name alternatives such as get_download_info, so it stops short of full when-to-use routing.

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 cover the read-only, non-destructive profile, and the description adds genuinely non-obvious behavior: DSM sorts folders and files in separate groups (so ascending puts folders first, descending files first) and long listings are paged with the next offset reported in the reply. It stops short of describing per-item fields or permission/error behavior, so not 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?

Four compact sentences, each earning its place: scope first, alternatives second, output caveats third, sorting/paging last. No filler or restatement of the tool name.

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

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

With no output schema, the description supplies the key return-shape facts an agent needs (paged results, next offset, folders have no size), which is exactly the right compensation. It omits what other per-item fields come back, a minor gap for a read-only listing tool with full parameter documentation.

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 cannot: the folder-vs-file sort grouping that determines what sort_direction actually yields, and the paging contract tying limit/offset to the reported next offset. Pattern and filetype semantics are left to the schema.

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

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

States a specific verb+resource ('List the files and folders') and immediately bounds scope ('directly inside one folder (one level; subfolders' contents aren't listed)'). It also names the sibling it is not (search_files for recursive lookups), so an agent can distinguish it without opening any schema.

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

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

Explicitly routes to alternatives with conditions: use search_files to find files anywhere below by name/extension/size/date, and get_dir_size for a folder's total size. It also pre-empts a likely misuse by noting folders report no size.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds useful behavioral detail — that results are paged and that substring name matching narrows the list. It does not discuss permissions needed for the shared space or how hidden people/concepts affect counts, but with annotations present the bar is lower and this is solid supplementary context.

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

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

Three sentences, front-loaded with the enumeration of types, then the use case, then the paging/filter note. Nothing is redundant or padded, and the reader gets the highest-value information 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 no output schema, the description correctly discloses what comes back — ids and item counts — and covers paging and filtering, which is what an agent needs to call it. The only gap is that the personal-vs-shared space semantics that affect ID validity are left entirely to the schema, so it falls just short of fully self-contained.

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

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

Schema coverage is 100%, so all seven parameters, including the enum-like `type` values and `space`, are already fully documented in the schema. The description only echoes the name-substring behavior and paging, adding no syntax or edge-case detail beyond what the schema states. Baseline 3 applies when the schema carries the parameter burden.

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

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

The description names a specific verb ('List') and resource ('Synology Photos collection') and enumerates the exact collection types it can return, including 'albums shared with you' as its own type. It also distinguishes itself from list_photos and the filesystem tools by framing the output as ids and item counts. An agent can identify this tool's domain without consulting 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?

It gives a concrete use case and routes the agent to the pairing sibling: 'Use it to find the ids and names that list_photos filters by.' That is clear usage context, but it stops short of exclusions — e.g., it never says to use list_photos or search_files instead when you merely want photo metadata rather than a collection listing.

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 a safe read operation, so the bar is lower, and the description still adds real behavior: default ordering is newest-first, the total is returned, and keyword search runs in search order with no sorting applied. It also enumerates the row fields, though it omits pagination behavior details beyond the offset/limit params.

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 purpose and the most consequential constraint (combination rules) before the return-shape and routing details. It is dense and slightly run-on but nearly every clause carries non-redundant 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 17-parameter, zero-required filter tool with no output schema, the description covers what the rows contain and how to chain into get_photo/download_photos, which is exactly the context an agent needs. Nothing critical 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 baseline would be 3, but the description adds cross-parameter semantics not present in the schema: the mutual-exclusion/combination rules between filter families and the note that IDs belong to one space. That is genuine meaning beyond the field-level descriptions.

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 ('List or search photos and videos in Synology Photos') with scope details (newest first by default, total included) and distinguishes itself from get_photo, download_photos, and File Station's list_files. An agent can tell exactly what this tool does and what it is not for.

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 encodes the combination rules: folder/person/tag combine with date/type/rating/favorite, while album/place/concept/keyword work alone. It also names downstream alternatives ('pass the ids to get_photo for full details or to download_photos') and the File Station alternative with its enablement condition.

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 destructiveHint=false, but the description adds substantial behavioral detail beyond them: top-level-only listing without a pattern, folder/file sorting parity with list_files, recursive search with pattern, caps of 200 folders and 5,000 items, early-stop notification, path reporting per match, and the distinction between file mtime and deletion time. No behavior contradicts 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?

The purpose and scope are front-loaded in the first sentence, followed by sibling routing and then behavioral nuances in a compact paragraph. Every sentence contributes distinct selection or invocation information, with no filler.

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

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

For a read-only listing tool with six parameters, full schema coverage, and no output schema, the description covers the important gaps: list behavior with and without pattern, search limits and early-stop signaling, path reporting, sorting, and the meaning of modified time. An agent has enough information to invoke it correctly.

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

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

Schema coverage is 100%, so the schema already defines each parameter. The description still adds useful meaning: it explains how pattern changes scope (search across the bin, subfolders included), describes the search caps, and clarifies that 'modified' is the file's own time rather than deletion time. This goes beyond schema restatement, though much of it is behavioral context rather than per-parameter syntax.

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

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

The description opens with a specific verb and resource: 'List what's in one shared folder's recycle bin: the files and folders deleted from that share.' It explicitly distinguishes this tool from list_shares (which shares have a bin) and list_files (non-deleted files), so an agent can select it without opening the schema.

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

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

It names two concrete alternatives and the conditions that select them: list_shares for checking which shares have a bin, and list_files for files that were not deleted. That provides explicit routing guidance and a clear when-not condition.

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/non-destructive, and the description adds real value beyond them: what each entry contains (volume, recycle-bin flag) and the caveat that free space is per-volume and shared across shares. It stops short of describing pagination or exact return shape, but the behavioral profile is clear.

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

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

Front-loaded with the core definition and the "call this first" directive before the details; three dense sentences that mostly earn their place, though the free-space parenthetical is slightly compressed.

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 usefully summarizes what is returned (volume, free space, recycle-bin status) and flags the shared-free-space nuance. It omits any mention of the sortable fields or the number/shape of entries, which is a minor gap.

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

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

Schema coverage is 100%, so sort_by and sort_direction are fully documented in the schema; the description says nothing about sorting. Baseline 3 applies since the schema carries this dimension.

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 all shared folders on the NAS") and adds a concrete definition ("the top-level folders every file path starts with (`/video`)"), which separates it cleanly from siblings like list_files or get_dir_size.

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 says "Call this first to discover paths" and routes the size question to get_dir_size, so both when-to-use and the alternative are stated outright.

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 destructiveHint=true and readOnlyHint=false, and the description adds important behavioral details: target keeps its id, merged people disappear, the operation is all-or-nothing if any person is missing, and the merge is irreversible. This gives the agent the operational context needed before invoking 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?

The description is tightly written and front-loaded: the merge behavior comes first, followed by the all-or-nothing rule, the irreversibility warning, and the sibling alternative. Every sentence carries useful information.

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

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

For a destructive mutation tool with no output schema, the description covers the essential risks and semantics: what gets merged, what survives, failure behavior, irreversibility, and which sibling to use for a related operation. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the parameters are already well documented. The description reinforces the target/merge relationship by stating that every person in merge joins target and target keeps its id, but it does not add meaning for the name or space parameters beyond what the schema already provides.

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: merge people/face-recognition groups in Synology Photos that are the same person. It explains the core effect—merge joins target, target keeps its id, merged people are gone—and distinguishes this from edit_person, which is for renaming or hiding one person.

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

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

It explicitly tells the agent when to use this tool (merging duplicate people) and when to use the sibling edit_person instead (renaming or hiding one person). It also gives a clear prerequisite: confirm with the user first because the action cannot be undone.

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

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

Goes well beyond the annotations: annotations only declare destructiveHint=true, while the description spells out that folders move recursively, that overwrite=false skips and lists existing destination items leaving them at source, that a missing source aborts the whole operation, and that long moves continue on the NAS and return a handle for file_task. These are the exact behaviors an agent needs before invoking a destructive 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?

Five short clauses, front-loaded with the core action and destruction consequence, then the alternative, then preconditions and edge cases. No sentence repeats the name or title and none could be dropped without losing a decision-relevant fact.

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

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

For a 3-parameter destructive tool with no output schema, the description covers the mutation effect, prerequisite state, partial-failure semantics, and the async escape hatch to file_task. Nothing an agent needs in order to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the all-or-nothing atomicity tied to `paths` ('if any source is missing, nothing is moved') and the fact that skipped items remain at the source under `overwrite=false`. It largely restates the `dest_folder` existence requirement already in the schema, keeping it short of a 5.

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

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

States a specific verb and resource (move files or folders into a destination folder) and immediately distinguishes the semantics from the closest sibling by noting that sources are removed and pointing to copy_files for the non-destructive variant. An agent can pick this over copy_files without inspecting either schema.

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

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

Explicitly names the alternative (copy_files) and the condition that selects it ('to keep the sources'). It also gives preconditions ('dest_folder must already exist; it isn't created') and the default-mode behavior, so both use and non-use are covered.

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 this as a write with destructiveHint=true, but the description adds genuinely new behavior: the 30 s task timeout, that longer moves keep running server-side, and that the reply carries a handle for photo_task. That async/completion detail is exactly what an agent needs and is not in annotations. It stops short of saying whether the move is reversible or how partial failures are reported.

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

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

Four dense sentences, front-loaded with the core action and immediately followed by the critical scope exclusion. The parenthetical workaround and the timeout clause are efficiently packed, though the timeout/handle sentence could be tightened without losing meaning.

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, and the description compensates by explaining the response behavior (task handle on timeout). Combined with 100% schema coverage and mutation annotations, an agent has everything needed to call this correctly, including the async continuation path via photo_task.

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 ids, folders, space, dest_space, destination and on_conflict are all documented at the field level. The description reinforces the space semantics ('another folder of the same space') and the overwrite effect, but adds no syntax or constraint detail beyond what the schema already states. Baseline 3 applies.

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

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

States a specific verb and resource set ('Move Synology Photos items and/or whole folders') plus the exact scope boundaries: within one space, or personal→Shared Space only. That scope statement separates it cleanly from copy_photos and move_files without the agent needing to open 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 explicit when-not guidance ('Photos can't move out of Shared Space') and names the workaround alternative ('copy, then delete'). The overwrite condition is also framed as a usage choice ('With on_conflict=overwrite it replaces files'), not just a parameter restatement.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false; the description goes far beyond that by disclosing partial-failure semantics, the 405/`not paused: already finished` per-id outcome, and the invalid_parameter whole-call failure conditions. This is exactly the kind of operational detail 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?

Front-loaded with the action in the first clause, then failure behavior, with zero filler sentences. The middle sentence is dense and its 'refused for its id (error 405) or shown as...' phrasing is slightly convoluted, but every clause carries information.

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

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

With one required parameter and no output schema, the description covers the decisive gaps: which ids fail, what happens on partial success, and where to check status via list_downloads. It does not say what a fully successful call returns, but that is a minor omission for a simple state-change tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: a missing id or another user's task causes the entire batch to fail with invalid_parameter rather than being silently skipped. That constraint on the task_ids array is not visible 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?

Names a specific verb and resource ("Pause one or more download tasks") and makes the batch scope explicit via "one or more." It is distinct from sibling resume_download by plain naming, but the description never explicitly contrasts the two, which keeps it just short of a 5.

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

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

Rather than generic 'when to use' prose, it enumerates the exact states in which the call succeeds, partially succeeds, or fails outright, which tells an agent precisely when invocation is appropriate. It lacks an explicit pointer to resume_download as the inverse operation, so it stops at 4.

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; the description adds the crucial nuance that item removal affects only album membership, not the underlying photos, and that set_condition *replaces* an existing smart album condition. It does not say whether operations are reversible or what error/permission conditions apply, but the mutation footprint is substantially clarified beyond the annotation.

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 operation list comes first, followed by the scope constraint, then sibling routing — front-loaded with zero filler. Every clause carries information an agent would otherwise have to infer.

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

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

Covers scope, per-action semantics, the nested condition object's role, and sibling boundaries for a 5-parameter mutation tool with no output schema. The remaining gap is what an invocation returns (e.g., the new album's ID for create/copy), which matters because there is no output schema to fall back on.

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

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

Schema description coverage is 100%, so the action-to-parameter mapping the description implies is already spelled out per-property in the schema. The description adds no syntax, format, or constraint detail absent from the schema (the 1,000-item cap, set_cover's single id, and condition fields all live in schema descriptions). Baseline 3 is appropriate.

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

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

Names a specific resource (Synology Photos album) and enumerates the concrete operations it performs: create, create_smart, rename, add/remove items, set cover, copy, set_condition. It also disambiguates from siblings by naming delete_photo_albums and photo_share_link as the tools for deletion and sharing, so an agent can pick the right tool without opening any schema.

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

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

Explicitly routes two adjacent jobs elsewhere ('To delete albums use delete_photo_albums; to share one, photo_share_link') and states a hard scope boundary ('Personal space albums only'). The 'photos themselves never move' line also tells the agent this is not a substitute for move_photos, which is the most likely confusion given the add/remove vocabulary.

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 and idempotentHint=true, and the description adds a real behavioral rule: a name already present in the parent is refused rather than overwriting. It also discloses the File Station-write prerequisite for the fallback path. It stops short of explaining why this mutating-but-non-deleting tool is flagged destructive, which would have closed the loop.

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

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

Three sentences, front-loaded with the core operation, then the collision rule, then sibling routing. No sentence is redundant and nothing is buried.

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

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

For a 6-parameter tool with no output schema, the description covers scope, failure behavior, prerequisites, and all sibling alternatives, while annotations carry the safety profile and the schema carries parameter semantics. Nothing an agent needs to select or invoke this correctly is missing.

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

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

Schema description coverage is 100% and every parameter — name, space, action, folder, parent, item_id — is documented inline, including per-action applicability. The description adds little beyond that, only hinting at the name-collision constraint. Baseline 3 is appropriate when the schema carries parameter meaning.

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

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

States specific verbs (create, rename, set cover) against a specific resource (folder in Synology Photos) and immediately scopes itself away from siblings like copy_photos, move_photos, and delete_photo_folders. An agent knows exactly what this tool does and does not cover without opening the schema.

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

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

Explicitly routes the agent: use copy_photos/move_photos for copying or moving, delete_photo_folders for deletion, and File Station's create_folder/rename for non-Photos folders, with the caveat that File Station write must be enabled or the user must act in DSM. That is when-to-use plus when-not-to-use plus alternatives in two sentences.

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

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

The description adds valuable operational context by defining the side effects of the actions (e.g., create returns the link, delete breaks it). While annotations cover the safety profile, this text clarifies the practical consequences of using the 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?

The description is highly efficient. It is a single, well-structured paragraph that clearly explains the scope and all possible functional states of the resource.

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 the high-quality input schema and clear behavioral hints, the description provides all necessary high-level context for an AI agent to select and correctly invoke the tool for CRUD operations.

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 coverage is 100%, so the structure of the parameters is fully documented. The description mainly summarizes the functionality rather than adding meaning to specific parameters like 'folder' or 'expires'.

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 immediately identifies the resource ('Synology Photos photo requests') and defines the management capabilities ('Manage... photo requests'), clearly distinguishing it from generic file upload/download 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?

It provides explicit usage guidance by defining the outcomes of the `action` parameter: 'create' returns a link, 'delete' makes it stop working. This helps the agent select the right operational mode based on its goal.

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 this is a destructive mutation (readOnlyHint=false, destructiveHint=true), and the description adds valuable behavioral detail beyond them: stopping preserves the link, sharing again resets settings, and password/expiry are refused without public access. It does not cover permissions or rate limits, but the added context is substantial.

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

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

The description is three tight sentences with no wasted words. The core purpose is front-loaded, followed by key behavioral constraints. Every sentence earns its place.

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

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

For a six-parameter mutation tool with no output schema, the description covers the essential calling context: action semantics, cross-parameter constraints, and personal-space-only scope. It does not describe return values, but the schema action descriptions partly compensate and the tool is still callable correctly 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 100%, so the schema already documents all parameters in detail. The description reinforces cross-parameter constraints (password/expiry need public view or download) and action semantics, but most of that information is already present in the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource (share a Synology Photos album by link) and enumerates the actions (change public access, password, expiry, members, stop sharing). It also scopes the tool to personal space albums only. However, it does not explicitly differentiate itself from sibling tools such as list_shares or photo_album.

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 clear when-to-use context and constraints: password or expiry requires public view or download, stopping keeps the link, and re-sharing resets settings. It also limits the tool to personal space albums. It stops short of naming alternative tools and when to prefer them.

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

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

Annotations only flag destructiveHint=true and readOnlyHint=false globally, but the description differentiates the actions themselves: status is a read, stop may leave the task 'partly done', clear removes only finished tasks. That partial-completion caveat is the key behavioral fact an agent needs and it is not in the annotations. Missing only permission/auth notes and what a handle looks like when stale.

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

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

Four compact sentences, front-loaded with the primary use case and with the anti-polling warning placed last as a guardrail. There is mild duplication of the schema's action enumeration, which is the only waste.

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, yet the description says what status yields (progress for a handle, otherwise this user's task list), which covers the return-value gap adequately for a 2-parameter tool. It stops short of describing task fields or how finished vs running tasks are distinguished in the list.

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

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

Schema coverage is 100%, and the schema already documents `action` (with its default and per-value meaning) and `handle` (including the `photos:14` example). The description largely restates that, adding only the 'handle a reply gave' provenance cue and the 'stop needs a handle' dependency.

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 the precise resource (a running Synology Photos copy/move/delete task) and the three operations keyed off the presence of a handle. An agent can distinguish it from copy_photos, move_photos, delete_photos and file_task 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 splits behavior on the `handle` parameter (with handle -> status/stop on that task; without -> list this user's tasks) and explicitly states when NOT to poll: 'check when the user asks, or before doing something that depends on the result.' That is a real usage constraint, not an inference.

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

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

Annotations already declare a non-destructive, non-read-only mutation, and the description adds the important failure semantics: a name collision is refused and nothing is replaced. It stops short of saying what the response looks like or whether the operation is atomic, but the key risk behavior is disclosed.

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, each doing work: what it does, what happens on conflict, and where to go instead. Front-loaded and free of filler.

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

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

For a two-parameter mutation with full schema coverage, this covers purpose, conflict behavior, and the sibling alternative. Minor gaps remain (return value, whether folders recurse or any permission prerequisites), but nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and both parameters have examples showing full path vs. bare name. The description's 'new name ... in that folder' reinforces the scoping but adds little beyond the schema itself, so the baseline 3 applies.

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

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

States a specific verb and resource ('Rename a file or folder') and adds the scope qualifier 'in place', which cleanly separates it from move_files. An agent can pick between the two without opening either schema.

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

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

Explicitly names the alternative ('use move_files') and the condition that selects it (moving to another folder). It also states the use case this tool does cover, so both branches of the decision 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 only declare non-read-only and destructive=true; the description goes well beyond them by disclosing atomic all-or-nothing semantics, folder re-creation, skip-vs-overwrite behavior, and that long restores continue server-side returning a handle for file_task. This is exactly the operational context an agent needs before a destructive call.

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

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

Front-loaded with the action and scope, then the precondition, then the parameter behaviors in a logical order. Dense but nearly every clause carries new information; a couple of clauses duplicate schema-documented defaults.

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 4-parameter mutation with no output schema, the description covers preconditions, partial-failure semantics, destination behavior, and the async continuation path (file_task). Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value with the 'flat' behavior of dest_folder and the re-creation of the original folder when dest_folder is omitted, plus how overwrite interacts with the skip rule. Some of the restatement of overwrite semantics overlaps the schema, keeping it off a 5.

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

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

Opens with a specific verb+resource+scope: 'Restore deleted files or folders from one shared folder's recycle bin.' It immediately distinguishes itself from the obvious sibling list_recycle_bin by naming it as the read-only precursor.

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 tells the agent to call list_recycle_bin first and states the hard precondition ('every path must be in that share's bin, or nothing is restored'), which is effectively a when-not-to-use condition. The alternative sibling is named with the condition that selects it.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the real behavioral load and does so: it discloses non-atomic batch semantics — an invalid id fails with error 405 while the remaining ids are still resumed. It doesn't say what the response looks like (counts, per-id results), which is the main remaining gap.

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

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

Three short sentences, zero waste. The operation and its failure mode are front-loaded, and the discovery hint trails where it belongs.

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 mutation with no output schema, the definition covers purpose, precondition, source of IDs, and partial-failure behavior. Only the shape of the return value on partial success is left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond the schema: it clarifies that task_ids is a batch (partial success per id) and where the IDs come from. That is meaningful semantics the schema item description only hints 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 (resume) and resource (paused download tasks) with explicit scope: 'one or more paused download tasks.' It is clearly distinguishable from the nearby pause_download and delete_download siblings without opening any 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 a concrete discovery path — 'list_downloads with status_filter=`paused` finds the paused tasks' — and states the precondition (task must be paused, otherwise 405). It does not name the inverse tool (pause_download) explicitly, but the when-to-use context is essentially complete.

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 destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: no-filter returns everything up to `limit`, and a timed-out search returns partial results with a notice. It doesn't cover result ordering or how truncation is signalled beyond 'says so', but that is a minor gap against solid annotation coverage.

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

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

Front-loaded with the core capability, then immediately routes to alternatives, then covers edge cases. Every sentence carries distinct information: scope, exclusions, default behavior, timeout semantics. No filler.

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

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

For an 11-parameter read tool with full schema coverage and no output schema, the description covers the essential unknowns: unfiltered behavior, the result cap, and partial results on timeout. Return-value shape is left unspecified, which is acceptable since the schema carries no output contract, but a note on result ordering would round it out.

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

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

Schema description coverage is 100%, so all 11 parameters are already documented in the schema, including wildcard, size units, and date formats. The description only re-states the `limit` cap ('up to `limit`') and adds nothing about parameter syntax beyond the schema, which is appropriate at the 100%-coverage baseline.

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) with clear scope (a folder and everything below it) and enumerates the filterable facets: name, extension, size, modified date. It explicitly names the two siblings it is not (list_files, get_dir_size), so an agent can distinguish it without opening any schema.

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

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

Gives explicit when-not rules: 'For what's in one known folder, use list_files; for how much space a folder uses, use get_dir_size, not a search.' It also documents the no-filter case ('returns everything under the folder, up to limit'), so an agent knows what an unqualified call does.

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?

Adds substantial behavior beyond annotations: partial-update semantics, admin-only rate fields, DSM silently ignoring them otherwise, the tool refusing them, and the per-user nature of default_destination. This is exactly the context an agent needs to avoid a false success.

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

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

Four tight sentences, front-loaded with what the tool does and then the permission caveats. No filler; each sentence carries 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?

No output schema exists, but the description covers the critical success/failure semantics for a destructive, idempotent setter: optionality, partial updates, admin-only fields, and per-user defaults. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, and each parameter already documents meaning and permissions. The description reinforces the permission model and partial-update behavior, but adds little parameter-level detail beyond the schema.

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

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

States a specific verb and resource: 'Set Download Station global configuration.' It is immediately distinguishable from read-only siblings like get_download_config, but it does not explicitly name alternatives or sibling boundaries.

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?

Explains that all parameters are optional and only passed fields update, and gives clear permission-based usage rules for rate fields vs. default_destination. It stops short of naming get_download_config or other alternatives explicitly.

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?

Adds substantial behavior beyond annotations: partial-update semantics, NAS-wide scope of the enable flags, local-time interpretation of schedule_plan, and the admin/manager requirement for plan and rate writes. It also discloses that a refused write applies nothing, which is important for a destructive/idempotent mutation.

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

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

Front-loads the action and sibling distinction, then packs the remaining sentences with scope, partial-update behavior, time semantics, and permission constraints. There is no filler or redundancy.

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

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

For a five-parameter mutation tool with full schema coverage and annotations covering safety traits, the description supplies the remaining operational context: partial update behavior, NAS-wide effects, local-time format implications, and permission failure behavior. Nothing essential 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%, so parameter definitions carry the baseline. The description still adds useful meaning by tying enabled and emule_enabled to a NAS-wide scope, explaining that plan/rates require elevated permissions, and reinforcing that unspecified parameters are left unchanged.

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 ("Set the Download Station schedule") and immediately distinguishes the read-only sibling by naming get_schedule. An agent can tell exactly what this tool changes versus what the companion tool retrieves.

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 says get_schedule shows the current schedule and clarifies that all parameters are optional so only passed fields are updated. That gives clear usage context, though it does not spell out when-not-to-use scenarios beyond the read/write split with get_schedule.

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

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

Goes well beyond the annotations by disclosing that tags are written into original files, that file dates and sizes change, and that items get re-indexed — material side effects an agent must know before calling. It also explains the tag lifecycle (a tag vanishes when unused), which is not inferable from destructiveHint alone.

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

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

Three sentences, front-loaded with the core action, then the side-effect warning, then the lifecycle/workflow note. No filler; every sentence carries distinct information.

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

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

For a mutation tool with no output schema, it covers side effects, batch limit context, and tag semantics thoroughly. It stops short of saying what a successful call returns (e.g., resulting tag set or status), which would close the last gap.

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

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

Schema description coverage is 100%, so ids, tags, space, and action are already documented with formats and defaults. The description adds only the incidental hint of list_photos tag= filtering for sourcing ids, so the baseline 3 applies.

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

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

States a specific verb pair (add/remove) on a specific resource (tags on Synology Photos items), which cleanly separates it from siblings like edit_photo or rename. An agent can identify its role 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?

Provides concrete workflow guidance: to delete a tag, remove it from every item (routing to list_photos tag=...), and to rename, add the new name then remove the old. It lacks an explicit 'when not to use' or contrast with edit_photo, but the operational routing is clear.

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 mark this as non-read-only and potentially destructive, and the description usefully clarifies the key destructive behavior: an existing NAS file of the same name is kept unless overwrite is true. This adds important safety context beyond the annotations. It does not discuss permissions or return behavior, but the overwrite semantics are well covered.

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

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

The description is short, front-loaded with the core action, and contains no filler. The semicolon cleanly introduces the two most important constraints: single-file scope and default non-overwrite 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?

Given the 100% schema coverage and annotations, the description is nearly complete for an upload tool: it explains the source/destination relationship, single-file limitation, and overwrite safety default. It could be slightly stronger by mentioning that dest_folder creation is controlled by create_parents or by naming an alternative for folder uploads, but those gaps are minor.

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

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

Schema coverage is 100%, so the schema already documents all five parameters, including overwrite, dest_folder, and create_parents. The description adds the single-file constraint and reinforces the overwrite default, but it does not add substantial meaning beyond the schema for most parameters.

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: upload one file from the local machine to a NAS folder. It also clarifies the scope by saying a local folder cannot be uploaded, which helps distinguish it from folder-oriented operations. It is clear but does not explicitly differentiate against sibling upload/download/file-management 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?

The description gives useful context that this tool uploads a single file and cannot upload a local folder, and it explains the default overwrite behavior. However, it does not say when to use this vs siblings such as copy_files, move_files, or download_file, nor does it name an alternative tool for folder uploads.

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

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

Annotations only say write, non-destructive; the description goes well beyond that with a 30s default / 45s max timeout, partial-batch semantics with the untried files list, the local read restriction, and the indexing lag that can hide taken dates and previews. These are exactly the operational facts an agent cannot get 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.