qURL

Extend qURL Expiration

extend_qurl

Push out the expiration of an active qURL by a relative duration when only more time is needed. Accepts various resource IDs and returns updated resource.

Instructions

Push out the expiration of an active qURL by a relative duration. Convenience wrapper for the most common update — equivalent to update_qurl({ resource_id, extend_by }). Use this when the only change you need is more time on the clock. Use update_qurl instead when you also need to change tags, description, or set an absolute expires_at. Use delete_qurl when you want to cut off access entirely. Accepts resource public keys, CRIDs, legacy r_ IDs, and q_ display IDs (q_ is auto-resolved to its parent resource). Not idempotent: calling twice with the same extend_by extends the expiration twice. If you need an absolute target, use update_qurl with expires_at so retries on transient errors don't double-push. Returns the updated resource with the new expires_at (same shape as get_qurl).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`extend_by`	Yes	Duration to extend by (e.g., "24h", "7d")
`resource_id`	Yes	The resource public key, CRID, legacy r_ ID, or qURL display ID (q_ prefix) to extend. If a q_ ID is passed, the API resolves it to the parent resource automatically.

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.

Changed5 schema fields changedv0.2.1Sep 19, 2026

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

changedInput schema / properties / resource_id / description

Previous value: -"The resource ID (r_ prefix) or qURL display ID (q_ prefix) to extend. 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 extend. 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 declare write and non-idempotent behavior, but the description adds practical context: calling twice extends twice, retries on transient errors can double-push, the q_ display ID is auto-resolved to the parent resource, and the return shape matches get_qurl. These are exactly the behavioral details the annotations don't capture, and there is 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.

Conciseness5/5

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

The core capability is front-loaded, and every subsequent sentence earns its place: equivalence to update_qurl, when-to-use/alternatives, accepted ID forms, non-idempotency warning, retry guidance, and return shape. It is dense but not bloated.

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 two-parameter mutating tool, the description covers operation semantics, sibling routing, ID input types, the non-idempotency risk, and the response shape reference. The output schema covers return-value details, and the annotations cover idempotency/safety, leaving no invocation-critical gap. The only minor omission is behavior on an inactive or already-expired qURL, but that doesn't impair correct selection or invocation.

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

Parameters4/5

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 both parameters well. The description still adds value by framing extend_by as a relative duration, contrasting it with absolute expires_at, and clarifying that resource_id accepts public keys, CRIDs, legacy r_ IDs, and auto-resolved q_ IDs.

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 opens with a specific verb and resource: 'Push out the expiration of an active qURL by a relative duration.' It then explicitly distinguishes this tool from update_qurl and delete_qurl, so an agent can separate it from the dozen sibling tools without opening their schemas.

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 selection rules: 'Use this when the only change you need is more time on the clock,' and names update_qurl for tag/description/absolute-time changes and delete_qurl for cutting off access. It even handles the retry edge case by steering agents toward update_qurl when an absolute expires_at is safer.

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

Deploy Server