export_submissions

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

Annotations only say the tool is not read-only, not idempotent, and not destructive. The description adds useful behavioral detail: it creates a generated file inside the given folder, defaults to the form's configured fileFormat, and returns JSON containing the created file's name. It stops short of covering overwrite behavior or naming conventions, but the main side effect 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?

The summary sentence is front-loaded and the Args/Returns sections are compact and purposeful. Every line earns its place: no repetition of schema fields, no filler, and the format options are listed efficiently.

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

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

For a three-parameter file-generating tool, the description covers the purpose, all parameters, defaults, allowed formats, and return shape. The output schema also exists to document the return value. Minor omissions like overwrite behavior and permissions are not critical for the core export scenario.

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

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

Schema description coverage is 0%, so the description must fully compensate, and it does. It explains form_id as a numeric ID, path as the destination folder inside the user's files with no trailing slash, and file_format as an optional override with explicit values 'csv', 'xlsx', 'ods' and the default behavior tied to the form's configuration.

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: 'Export submissions to a spreadsheet file in the user's Nextcloud storage.' It clearly identifies the action, the data being exported, and the destination, and it differentiates the tool from read-oriented siblings like list_submissions and get_submission.

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 establishes a clear use context: exporting submissions into a folder in the user's storage, with optional format override. It does not explicitly name alternatives or say when not to use it, but the intended task is unambiguous and the parameter constraints (e.g., no trailing slash in path) guide correct invocation.

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