qURL

Batch Create qURLs

batch_create_qurls

Batch-create up to 100 qURLs in one call, with per-item success/error details. Avoids repeated single-URL requests when provisioning many expiring, scope-limited links at once.

Instructions

Create up to 100 qURLs in a single request. The single-call alternative to looping create_qurl — saves round trips and returns a single envelope of per-item results. Only use this when the user explicitly wants multiple qURLs in one request. Never use it for a single URL, a single file, a single image, or a single attachment. Do not use this tool for uploaded files, image attachments, PDFs, or base64 file content — use upload_file_data_qurl (HTTP mode) or upload_file_qurl (stdio mode) instead. Not transactional: items succeed or fail independently (see succeeded/failed counts and per-item error). Use this when you need to mint many qURLs at once (e.g. provisioning a vendor list, distributing per-customer share links). Use create_qurl for a single resource. Response shape: { succeeded: number, failed: number, results: BatchItemResult[], request_id?: string }. Each results[i] carries index (matching the input position), success, plus either qurl_link + resource_id + qurl_site + expires_at (success) OR error: { code, message } (failure). Successful items may also carry branded_domain for custom-domain anchor text. Partial failure signaling: the handler sets isError: true on the tool response whenever failed > 0, so agents can branch without parsing JSON. The HTTP layer also returns 400 when every item fails — that's surfaced through the same shape (read data.results[*].error). One-shot links: like create_qurl, every qurl_link in the response is shown ONCE. Don't lose them.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`items`	Yes	Array of qURL creation requests (1-100 items)

Output Schema

TableJSON Schema

Name	Required	Description	Default
`failed`	Yes
`results`	Yes
`succeeded`	Yes
`request_id`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed38 schema fields changedv0.2.1Sep 19, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```
removedInput schema / properties / items / items / additionalProperties
```
Removed value: -false
```
removedInput schema / properties / items / items / properties / access_policy / additionalProperties
```
Removed value: -false
```
removedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / additionalProperties
```
Removed value: -false
```

changed

Input schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / allow_categories / description

Previous value: -"AI agent categories to permit (all others blocked)"New value: +"AI agent categories to permit (all others blocked; max 20 entries, 128 chars each)"

addedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / allow_categories / items / maxLength
```
Added value: +128
```
addedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / allow_categories / items / minLength
```
Added value: +1
```
addedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / allow_categories / maxItems
```
Added value: +20
```

changed

Input schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / deny_categories / description

Previous value: -"AI agent categories to block (e.g., gptbot, commoncrawl)"New value: +"AI agent categories to block (e.g., gptbot, commoncrawl; max 20 entries, 128 chars each)"

addedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / deny_categories / items / maxLength
```
Added value: +128
```
addedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / deny_categories / items / minLength
```
Added value: +1
```
addedInput schema / properties / items / items / properties / access_policy / properties / ai_agent_policy / properties / deny_categories / maxItems
```
Added value: +20
```

changedInput schema / properties / items / items / properties / access_policy / properties / geo_allowlist / description

Previous value: -"Allowed country codes (ISO 3166-1 alpha-2)"New value: +"Allowed country codes (ISO 3166-1 alpha-2; max 50 entries, 8 chars each)"

addedInput schema / properties / items / items / properties / access_policy / properties / geo_allowlist / items / maxLength
```
Added value: +8
```
addedInput schema / properties / items / items / properties / access_policy / properties / geo_allowlist / items / minLength
```
Added value: +1
```
addedInput schema / properties / items / items / properties / access_policy / properties / geo_allowlist / maxItems
```
Added value: +50
```

changedInput schema / properties / items / items / properties / access_policy / properties / geo_denylist / description

Previous value: -"Denied country codes (ISO 3166-1 alpha-2)"New value: +"Denied country codes (ISO 3166-1 alpha-2; max 50 entries, 8 chars each)"

addedInput schema / properties / items / items / properties / access_policy / properties / geo_denylist / items / maxLength
```
Added value: +8
```
addedInput schema / properties / items / items / properties / access_policy / properties / geo_denylist / items / minLength
```
Added value: +1
```
addedInput schema / properties / items / items / properties / access_policy / properties / geo_denylist / maxItems
```
Added value: +50
```

changedInput schema / properties / items / items / properties / access_policy / properties / ip_allowlist / description

Previous value: -"Allowed IP addresses or CIDR ranges"New value: +"Allowed IP addresses or CIDR ranges (max 100 entries, 64 chars each)"

addedInput schema / properties / items / items / properties / access_policy / properties / ip_allowlist / items / maxLength
```
Added value: +64
```
addedInput schema / properties / items / items / properties / access_policy / properties / ip_allowlist / items / minLength
```
Added value: +1
```
addedInput schema / properties / items / items / properties / access_policy / properties / ip_allowlist / maxItems
```
Added value: +100
```

changedInput schema / properties / items / items / properties / access_policy / properties / ip_denylist / description

Previous value: -"Denied IP addresses or CIDR ranges"New value: +"Denied IP addresses or CIDR ranges (max 100 entries, 64 chars each)"

addedInput schema / properties / items / items / properties / access_policy / properties / ip_denylist / items / maxLength
```
Added value: +64
```
addedInput schema / properties / items / items / properties / access_policy / properties / ip_denylist / items / minLength
```
Added value: +1
```
addedInput schema / properties / items / items / properties / access_policy / properties / ip_denylist / maxItems
```
Added value: +100
```
changedInput schema / properties / items / items / properties / access_policy / properties / user_agent_allow_regex / description
```
Previous value: -"Regex to allow matching user agents"New value: +"Regex to allow matching user agents (max 256 chars)"
```
addedInput schema / properties / items / items / properties / access_policy / properties / user_agent_allow_regex / maxLength
```
Added value: +256
```
changedInput schema / properties / items / items / properties / access_policy / properties / user_agent_deny_regex / description
```
Previous value: -"Regex to deny matching user agents"New value: +"Regex to deny matching user agents (max 256 chars)"
```
addedInput schema / properties / items / items / properties / access_policy / properties / user_agent_deny_regex / maxLength
```
Added value: +256
```

changedInput schema / properties / items / items / properties / custom_domain / description

Previous value: -"Custom domain to assign to the auto-created resource"New value: +"Custom domain to assign to the auto-created resource (max 253 chars, must be registered/active/owned)."

addedInput schema / properties / items / items / properties / custom_domain / maxLength
```
Added value: +253
```

changedInput schema / properties / items / items / properties / max_sessions / description

Previous value: -"Maximum concurrent sessions (0 = unlimited, max 1000)"New value: +"Maximum concurrent sessions for this qURL token (0 = unlimited when one_time_use is explicitly false; max 1000)"

changedInput schema / properties / items / items / properties / session_duration / description

Previous value: -"How long access lasts after clicking (e.g., \"1h\")"New value: +"How long access lasts after the recipient reaches the content (e.g., \"1h\"). This anchors the resource-level session-duration cap when a new resource is created."

addedInput schema / properties / items / items / properties / type

Added value: +{
+  "description": "Resource type for integrations allowed to mint non-url qURLs (max 64 chars). Defaults to url.",
+  "maxLength": 64,
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "failed": {
+      "type": "number"
+    },
+    "request_id": {
+      "type": "string"
+    },
+    "results": {
+      "items": {
+        "description": "Per-item result. Discriminated on `success`.",
+        "oneOf": [
+          {
+            "additionalProperties": {},
+            "properties": {
+              "branded_domain": {
+                "description": "Bare branded hostname for anchor text when the resource has a usable custom domain",
+                "type": "string"
+              },
+              "expires_at": {
+                "type": "string"
+              },
+              "index": {
+                "description": "Index of the corresponding item in the input `items` array",
+                "type": "number"
+              },
+              "qurl_link": {
+                "description": "One-shot display access link — shown ONCE on creation",
+                "type": "string"
+              },
+              "qurl_site": {
+                "type": "string"
+              },
+              "resource_id": {
+                "type": "string"
+              },
+              "success": {
+                "const": true,
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "index",
+              "success",
+              "resource_id",
+              "qurl_link",
+              "qurl_site",
+              "expires_at"
+            ],
+            "type": "object"
+          },
+          {
+            "additionalProperties": {},
+            "properties": {
+              "error": {
+                "additionalProperties": {},
+                "properties": {
+                  "code": {
+                    "type": "string"
+                  },
+                  "message": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "code",
+                  "message"
+                ],
+                "type": "object"
+              },
+              "index": {
+                "description": "Index of the corresponding item in the input `items` array",
+                "type": "number"
+              },
+              "success": {
+                "const": false,
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "index",
+              "success",
+              "error"
+            ],
+            "type": "object"
+          }
+        ]
+      },
+      "type": "array"
+    },
+    "succeeded": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "succeeded",
+    "failed",
+    "results"
+  ],
+  "type": "object"
+}

First observedv0.2.0Apr 27, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Adds substantial behavior beyond the sparse annotations: 'Not transactional: items succeed or fail independently', the isError:true signaling convention, the HTTP 400-on-total-failure behavior, and the critical 'One-shot links... shown ONCE. Don't lose them' warning. No contradiction with readOnlyHint=false/idempotentHint=false — creating new batch links is a non-idempotent write, which the description matches.

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

Conciseness4/5

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

Dense but well-organized with bold headers and a logical flow from purpose → routing → behavior → response → warning. Minor deductions: the response-shape section is verbose given an output schema exists (which per rubric makes return-value explanation optional), and the batch-vs-single theme is restated several times. Every sentence still earns its place, but some could be trimmed.

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

Completeness5/5

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

For a complex batch tool with per-item failures, HTTP status quirks, and destructive-to-lose one-shot links, the description covers every decision an agent needs: when to invoke, what the per-item response looks like, how to detect partial failure without parsing JSON, and the irreversible nature of the links. Input schema covers parameters, output schema covers return types, and the description fills the behavioral gaps.

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

Parameters3/5

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

Schema coverage is 100% with a clear description of the `items` array and every nested property, so the schema carries the semantic load. The description reinforces the batch envelope concept and per-item result mapping, but adds no new input-parameter semantics beyond what the schema already documents. Baseline 3 is correct.

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

Purpose5/5

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

Starts with a specific verb+resource+scope: 'Create up to 100 qURLs in a single request.' It distinguishes itself from siblings explicitly — 'single-call alternative to looping create_qurl' and 'Use create_qurl for a single resource' — so an agent can tell batch creation apart from single creation and file upload 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.

Usage Guidelines5/5

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

Provides explicit when-to-use ('only when the user explicitly wants multiple qURLs in one request', 'mint many qURLs at once'), explicit when-not-to-use ('Never use it for a single URL...'), and names concrete alternatives with conditions ('use upload_file_data_qurl (HTTP mode) or upload_file_qurl (stdio mode) instead'). Nothing is left to inference.

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

Deploy Server