qURL

Update qURL

update_qurl

Update a qURL's expiration, tags, description, custom domain, or proxy host behavior. Accepts public keys, CRIDs, legacy r_ IDs, and q_ display IDs; q_ IDs resolve automatically for metadata changes.

Instructions

Update a qURL's expiration, tags, description, custom domain, or proxy host-header behavior. The richer alternative to extend_qurl — use update_qurl whenever you need anything beyond a relative time push. Accepts resource public keys, CRIDs, legacy r_ IDs, and q_ display IDs for expiration, tags, and description updates (q_ is auto-resolved); custom domain and preserve_host updates require a resource identifier (public key, CRID, or legacy r_ ID) because the qURL API now serves them from PATCH /v1/resources/{id}. Constraints: extend_by and expires_at are mutually exclusive; custom_domain/preserve_host cannot be combined with expiration changes in one call; at least one update field (extend_by, expires_at, tags, description, custom_domain, preserve_host) must be set. Clearing fields: pass description: "", tags: [], or custom_domain: "" to clear those fields explicitly. Use extend_qurl when the only change is a relative time push. Use delete_qurl when you want to revoke entirely. Errors: if the input fails schema refinements (both extend_by + expires_at, or no fields set), the handler returns an isError: true content block before any API call. Other API errors throw with the API's code/statusCode. Returns the updated resource (same shape as get_qurl).

Input Schema

TableJSON Schema

Name	Required	Description
`tags`	No	Replace all tags on this resource (max 10 tags, each 1-50 chars)
`extend_by`	No	Duration to extend by (e.g., "24h", "7d"). Mutually exclusive with expires_at.
`expires_at`	No	Absolute expiration timestamp (RFC 3339). Mutually exclusive with extend_by.
`description`	No	Replace the resource description (max 500 chars)
`resource_id`	Yes	The resource public key, CRID, legacy r_ ID, or qURL display ID (q_ prefix) to update. If a q_ ID is passed, the API resolves it to the parent resource automatically.
`custom_domain`	No	Replace the custom domain bound to this resource (max 253 chars, must be registered/active/owned). Pass "" to clear.
`preserve_host`	No	Whether to preserve the original Host header when proxying via the custom domain. Only meaningful when custom_domain is set; default false on the API side.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`slug`	No	Immutable per-owner resource identity, when one was supplied at create time
`tags`	No
`qurls`	No
`status`	Yes		unknown
`qurl_site`	No
`created_at`	Yes
`expires_at`	Yes
`qurl_count`	No	Number of access tokens minted for this resource
`target_url`	No	Underlying URL the qURL protects; omitted on connector-owned resources
`description`	No
`resource_id`	Yes	Stable resource identifier (public key or legacy r_ ID)
`custom_domain`	No
`preserve_host`	No	When true, the original Host header is preserved when proxying via the custom domain. Only meaningful when custom_domain is set; defaults to false on the API side.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv0.2.1Sep 19, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

addedInput schema / properties / custom_domain

Added value: +{
+  "description": "Replace the custom domain bound to this resource (max 253 chars, must be registered/active/owned). Pass \"\" to clear.",
+  "maxLength": 253,
+  "type": "string"
+}

addedInput schema / properties / expires_at / pattern

Added value: +"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"

addedInput schema / properties / preserve_host

Added value: +{
+  "description": "Whether to preserve the original Host header when proxying via the custom domain. Only meaningful when custom_domain is set; default false on the API side.",
+  "type": "boolean"
+}

changedInput schema / properties / resource_id / description

Previous value: -"The resource ID (r_ prefix) or qURL display ID (q_ prefix) to update. If a q_ ID is passed, the API resolves it to the parent resource automatically."New value: +"The resource public key, CRID, legacy r_ ID, or qURL display ID (q_ prefix) to update. If a q_ ID is passed, the API resolves it to the parent resource automatically."

removedInput schema / properties / resource_id / minLength
```
Removed value: -1
```

addedInput schema / properties / resource_id / pattern

Added value: +"(?:^(r_[a-z0-9_-]{11}|(?:[A-Za-z0-9_-]{4}){27,53}|(?:[A-Za-z0-9_-]{4}){27,53}[A-Za-z0-9_-]{2}|(?:[A-Za-z0-9_-]{4}){26,52}[A-Za-z0-9_-]{3}|[a-z2-7]{47}|[a-z2-7]{60})$)|(?:^q_[0-9a-f]{11}$)"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "created_at": {
+      "type": "string"
+    },
+    "custom_domain": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "description": {
+      "type": "string"
+    },
+    "expires_at": {
+      "type": "string"
+    },
+    "preserve_host": {
+      "description": "When true, the original Host header is preserved when proxying via the custom domain. Only meaningful when custom_domain is set; defaults to false on the API side.",
+      "type": "boolean"
+    },
+    "qurl_count": {
+      "description": "Number of access tokens minted for this resource",
+      "type": "number"
+    },
+    "qurl_site": {
+      "type": "string"
+    },
+    "qurls": {
+      "items": {
+        "additionalProperties": {},
+        "description": "Single access token belonging to a qURL resource",
+        "properties": {
+          "access_policy": {
+            "additionalProperties": {},
+            "description": "Access control policy snapshot for this token",
+            "properties": {
+              "ai_agent_policy": {
+                "additionalProperties": {},
+                "properties": {
+                  "allow_categories": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "block_all": {
+                    "type": "boolean"
+                  },
+                  "deny_categories": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  }
+                },
+                "type": "object"
+              },
+              "geo_allowlist": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "geo_denylist": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "ip_allowlist": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "ip_denylist": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "user_agent_allow_regex": {
+                "type": "string"
+              },
+              "user_agent_deny_regex": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "created_at": {
+            "type": "string"
+          },
+          "expires_at": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "max_sessions": {
+            "type": "number"
+          },
+          "one_time_use": {
+            "type": "boolean"
+          },
+          "qurl_id": {
+            "type": "string"
+          },
+          "qurl_site": {
+            "type": "string"
+          },
+          "session_duration": {
+            "description": "Seconds of access granted after a successful resolve",
+            "type": "number"
+          },
+          "status": {
+            "default": "unknown",
+            "description": "Per-token status (wider than resource status — tokens may be consumed/expired independently)",
+            "enum": [
+              "active",
+              "consumed",
+              "expired",
+              "revoked",
+              "unknown"
+            ],
+            "type": "string"
+          },
+          "use_count": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "qurl_id",
+          "status"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "resource_id": {
+      "description": "Stable resource identifier (public key or legacy r_ ID)",
+      "type": "string"
+    },
+    "slug": {
+      "description": "Immutable per-owner resource identity, when one was supplied at create time",
+      "type": "string"
+    },
+    "status": {
+      "default": "unknown",
+      "enum": [
+        "active",
+        "revoked",
+        "expired",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "tags": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "target_url": {
+      "description": "Underlying URL the qURL protects; omitted on connector-owned resources",
+      "type": "string"
+    }
+  },
+  "required": [
+    "resource_id",
+    "expires_at",
+    "created_at",
+    "status"
+  ],
+  "type": "object"
+}

First observedv0.2.0Apr 27, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, but the description adds crucial behavioral details: mutual exclusivity of extend_by/expires_at, the constraint that custom_domain/preserve_host cannot combine with expiration changes, the requirement of at least one update field, how to clear fields, error behavior (isError:true content block before API call for schema refinements, API errors throw with code/statusCode), and the return shape. This far exceeds the baseline and aligns with annotations (no contradiction).

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?

The description is a single dense paragraph but every sentence earns its place, covering purpose, usage, constraints, error handling, and return. It is front-loaded with purpose and the alternative. However, it could benefit from structured bullets for constraints and clearing fields to improve scannability. Still, it is not overly verbose relative to the information conveyed.

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?

The tool is complex with 7 parameters, but the description covers all critical aspects: identifier types, constraints, clearing, error behavior, and return shape (same as get_qurl). An output schema exists, and the description explicitly references it, so nothing essential is missing for an agent to call this tool correctly.

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

Parameters5/5

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

Schema coverage is 100%, and the description adds meaning beyond the schema: it explains the identifier formats accepted (public keys, CRIDs, legacy r_ IDs, q_ display IDs), that q_ is auto-resolved, and that custom_domain/preserve_host require a resource identifier due to the API endpoint change. It also clarifies mutual exclusivity and field-clearing semantics. This adds significant value on top of the schema.

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?

The description states a specific verb and resource: 'Update a qURL's expiration, tags, description, custom domain, or proxy host-header behavior.' It explicitly names the richer alternative to extend_qurl, distinguishing it from siblings. The purpose is unambiguous and immediately actionable.

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?

The description provides explicit guidance: 'Use extend_qurl when the only change is a relative time push. Use delete_qurl when you want to revoke entirely.' It also clarifies when update_qurl is appropriate ('whenever you need anything beyond a relative time push'). This directly addresses when-to-use and when-not-to-use with named alternatives.

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

Deploy Server