set_file_reminder

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds critical behavioral details: due date must be ISO 8601 with timezone, must be in the future, past timestamps are rejected, and setting a new reminder replaces an existing one. It also states the return shape. No contradiction with 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 description is front-loaded with the purpose, then adds validation rules, parameter details, and return info in a clean, scannable format. Every sentence adds essential information; there is no filler or repetition of schema metadata.

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 tool, the description covers all necessary context: what the tool does, constraints on both parameters, replacement behavior, and the return confirmation. The presence of an output schema plus the explicit return description leaves no material gap for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains file_id as a numeric Nextcloud file id and due_date as an ISO 8601 timestamp with timezone, including concrete examples and the future-date constraint. This fully documents both required parameters beyond the bare schema titles.

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 'Set or update the reminder on a file,' which names a specific verb, resource, and operation. It clearly distinguishes itself from sibling tools get_file_reminder and remove_file_reminder by defining exactly what action it performs.

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 clearly establishes the operation's context: it sets or updates a reminder, replaces any existing reminder, and rejects past timestamps. It doesn't explicitly say 'use get_file_reminder to read or remove_file_reminder to delete,' but the set vs. get vs. remove distinction is evident from the tool names and the described behavior.

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