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.

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.

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.

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.

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.

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.

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

Annotations already indicate non-idempotence and non-read-only, but the description goes far beyond them: it states calling twice produces two distinct tokens, the qurl_link is shown once and is never recoverable, the API defaults expires_in to 24h, and max_sessions is per-token rather than resource-wide. These are critical behavioral traits that structured fields alone do not convey.

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 long but every sentence earns its place: definition, usage rules, behavioral caveats, return format, and a concrete example. It uses bolded section labels for scannability and front-loads the tool's purpose before routing to alternatives. The density is justified by the tool's complexity and nine parameters.

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?

Given the tool's complexity, rich schema, and large sibling set, the description is complete. It covers selection criteria, side effects, security-relevant one-time display of the link, default expiry, parameter semantics, and the exact return shape, including the fact that qurl_id is the only persistent handle. An agent has everything needed to invoke and follow up 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 100%, so the baseline is 3. The description adds meaningful guidance beyond the schema: target_url groups to an existing same-type resource, expires_in defaults to 24h, max_sessions: 0 requires explicit one_time_use: false, and the returned resource enters active status. This elevates the score above baseline, though not all nine parameters are individually discussed.

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 precise verb+object: 'Create a qURL — a policy-bound, expiring access link that gates a target URL.' It enumerates the optional filters and limits, and explicitly names sibling tools it is not, such as mint_link and batch_create_qurls, so an agent can distinguish it without inspecting schemas.

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 contains explicit 'When to use', 'Do NOT use', and 'When NOT to use' guidance. It names concrete alternatives (upload_file_data_qurl, upload_file_qurl, mint_link, batch_create_qurls, update_qurl) and provides a clear chat-upload exclusion, leaving no ambiguity about when this tool should be selected.

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

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

While annotations already declare destructiveHint and idempotentHint, the description adds significant context: irreversibility, the 404-collapsing behavior for ownership-mismatch (avoiding existence disclosure), the branch on was_already_revoked, the effect on list_qurls, and the recommendation to verify ownership via get_qurl. This goes well beyond what annotations state.

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 moderately long but every sentence carries necessary information: core purpose first, then alternatives, then idempotency, ownership handling, return payload, and listing behavior. It is logically ordered and free of filler.

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?

The description fully covers the tool's behavior for an agent: purpose, usage conditions, idempotency edge cases, ownership implications, return payload indication, and post-revoke visibility. With an output schema present, the return details are appropriately summarized.

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 100%, and the schema's resource_id description already explains accepted ID formats and what it revokes. The tool description does not add new parameter semantics beyond that, so a baseline score of 3 is appropriate.

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 precise verb ('revoke') and resource ('qURL'), explains the immediate effect (link and all access tokens stop working), and explicitly contrasts with update_qurl and extend_qurl, making the tool's purpose unmistakable even without opening sibling schemas.

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?

It provides explicit when-to-use guidance (compromised link, departed user, end-of-engagement) and names the exact alternatives (update_qurl for non-destructive edits, extend_qurl for expiration-only changes), leaving no ambiguity about tool selection.

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

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.

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.

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.

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.

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.

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.

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

The annotations establish readOnly, idempotent, and non-destructive behavior, so the description correctly builds on that rather than repeating it. It adds genuinely useful behavioral caveats: qurls[] is an unordered preview capped at 100 rows, may be omitted on list views or redacted resources, qurl_count should be used to detect more rows, and the one-shot qurl_link from creation is never returned. This is far beyond what annotations alone communicate.

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 longer than average, but it is front-loaded with the core purpose and then systematically covers alternatives, exclusions, and behavioral caveats. Each sentence adds distinct information; however, a few clauses could be tightened without loss, so it earns a 4 rather than a 5.

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?

Given a single parameter, rich schema coverage, an output schema, and safety annotations, the description supplies all necessary context: purpose, routing among many siblings, known limitations, and edge-case output behavior. An agent has enough information to select and invoke this tool correctly without further clarification.

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 100%, and the schema already documents the resource_id patterns, the accepted ID forms, and the q_ auto-resolution behavior. The tool description enriches the conceptual context but does not need to repeat the parameter mechanics; the schema carries the semantic load, so the baseline of 3 is appropriate.

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 names a specific verb and resource ('Fetch a single qURL resource by ID') and states exactly what is returned ('current state plus a bounded preview of access tokens'). It also distinguishes this tool from siblings by explicitly noting it is not for creating, listing, or resolving qURLs.

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 gives explicit when-to-use conditions (having a resource_id or q_ display ID), explicit when-not-to-use conditions (creating a qURL for a freshly uploaded file), and names concrete alternatives (`list_qurls`, `resolve_qurl`, `upload_file_data_qurl`). It even clarifies the common user request 'qURL of this image/file' and when this tool is not the right choice.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description reinforces these. More importantly, it adds behavioral detail beyond annotations: empty data[] semantics, cursor-based pagination rules, default status filtering, invalid status values, and sort defaults. This gives the agent a precise model of how the tool behaves at runtime.

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 well-structured with bolded sections and front-loaded purpose, but it is long and repeats some information already present in the schema (e.g. default status and sort). The density is mostly justified by the tool's complexity, though slight trimming would improve conciseness.

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 tool with 9 optional filter/pagination parameters, the description covers discovery scenarios, exclusions, filter semantics, pagination, default behavior, and return shape. Even with an output schema present, it explains the meta contract and edge cases (e.g. expires_at not changing status), making it complete for correct invocation.

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 coverage is 100%, so the baseline is 3, but the description adds substantial semantic value: filters AND together, defaults ('active', page size 20, sort created_at:desc), the meaning of passing meta.next_cursor as cursor, and invalid filter combinations. These interaction-level details are not evident from individual property descriptions alone.

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: 'List qURL resources, paginated and optionally filtered by status, date range, or search text.' It also differentiates itself from siblings by explicitly contrasting with get_qurl and resolve_qurl, so an agent can immediately distinguish this listing operation from related ones.

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 provides a dedicated 'When to use' section for discovery/audit scenarios and a 'When NOT to use' section naming get_qurl for known IDs and resolve_qurl for opening access. This is explicit, actionable routing guidance that leaves little to inference.

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

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

Annotations already carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the bar is lowered. The description reinforces these and adds an interpretive detail: empty data[] means no active sessions. It does not elaborate on session expiration or auth requirements, but the annotations adequately cover the safety profile.

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?

Three tight sentences: primary action, usage alternatives, and a clear behavior note. Every sentence earns its place with no filler, and the most important information is front-loaded.

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 one-parameter read-only list tool with an output schema and comprehensive annotations, the description fully covers purpose, workflow, alternatives, and the meaning of an empty response. Nothing essential for correct invocation or selection is missing.

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 100%, with resource_id fully documented by type, pattern, and description. The description adds no parameter-specific detail, but none is required because the schema already carries the semantic load.

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?

States 'List active access sessions for a qURL resource' – a specific verb and resource with a clear scope. It also distinguishes itself from siblings by clarifying that it shows live session state, not token/resource metadata (get_qurl) or session termination (terminate_qurl_sessions).

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?

Provides explicit when-to-use and when-not-to-use guidance: inspect sessions before rotating/revoking/terminating, use terminate_qurl_sessions when sessions should be ended, and use get_qurl when metadata is needed instead of active session state. This gives an agent concrete decision rules for tool selection.

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

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

It discloses behavior not visible from annotations: one-shot display semantics, mutual exclusivity of expires_in and expires_at with an isError: true result, the 24-hour default when neither is set, and the need to capture qurl_id because the link is not returned again. These details extend the annotations without contradicting them.

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 longer than average but every clause earns its place, and bold labels like 'Constraints:' and 'Output:' keep it scannable. It front-loads the core purpose before alternatives and edge conditions, making good use of structure given the tool's complexity.

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?

With 8 parameters, nested access_policy objects, and an output schema, the description covers what an agent needs: when to call the tool, which ID forms are accepted, expiry edge cases, and what to capture after a successful call. The presence of an output schema means return-value details do not need to be repeated in prose.

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?

Although schema coverage is 100%, the description adds decisive parameter-level meaning: accepted resource ID forms including q_ resolution, expiry mutual exclusivity and defaulting behavior, and the one-shot output implication for qurl_id. These are cross-parameter constraints the schema alone does not fully express.

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 uses the specific verb 'mint' with a clear resource: a fresh access link attached to an existing qURL resource. It immediately differentiates from siblings by stating it shares one-shot display semantics with create_qurl.qurl_link but does not create a brand-new resource, and it names update_qurl as a separate alternative.

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?

Explicitly states when to use mint_link (issue additional access links for a second recipient or replacement) and when not to: create_qurl for a brand-new resource, and update_qurl for changing expiration/tags/description on the existing resource. This gives an agent a clear, actionable decision rule.

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

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

Goes well beyond the annotations by disclosing concrete side effects: consumes one-time-use tokens, decrements max_sessions, and may trip access policies. It also explains the idempotentHint:false annotation by distinguishing conservative worst-case behavior from the actual no-op behavior for non-one-time tokens within an active grant window.

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?

Well-organized and front-loaded: core action first, then when to use, then the alternative, then side effects, then idempotency nuance. Each sentence serves a distinct purpose and no space is wasted on repetition.

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 token-redemption tool with an output schema and annotations, the description covers the action, usage boundary, side effects, and annotation rationale. Everything an agent needs to decide to call it and interpret its behavior is present.

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 coverage is 100% with an example value, but the description adds useful context: the token originates from a qurl_link and carries the at_ prefix. This helps agents recognize and source the parameter correctly without replacing schema documentation.

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?

Opens with a specific verb-object pair, 'Redeem a qURL access token', and states the outcome: reveal the underlying URL and obtain a time-bound, IP-bound grant. It also explicitly differentiates itself from get_qurl by token type vs resource identifier, making it unmistakable.

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?

Provides explicit when-to-use guidance ('Use this when an agent has been handed an access token and needs to fetch the protected resource') and explicit when-not-to-use guidance with the named alternative ('Use get_qurl instead when you have a resource identifier...'). No inference required.

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

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

Annotations already mark the tool as destructive and non-idempotent, and the description adds useful behavior beyond that: re-revoking an inactive token returns an API error rather than being idempotent. It also clarifies the operation is scoped so sibling tokens stay active, which adds context not fully carried by 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 core action, immediately gives the use case, names the alternative tool, and ends with constraints and error behavior. Every sentence earns its place with no repetition or filler.

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 with an output schema, annotations, and sibling tools present, the description is complete: it explains what it does, when to choose it, when not to, required IDs, and non-idempotent behavior. Nothing an agent needs to call it correctly is missing.

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 coverage is 100% and both params have descriptions and patterns, so the schema already does most of the work. The description adds a slight semantic benefit by labeling resource_id as the parent and tying qurl_id to the token display ID, but it does not fundamentally go beyond the schema.

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 has a specific verb and resource: 'Revoke one qURL token under a resource without revoking the whole resource.' It clearly distinguishes this tool from delete_qurl by scoping the action to a single token rather than the entire resource.

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?

Explicitly states when to use: when a single recipient/link should stop working but sibling qURLs on the same resource_id must remain active. It also names the alternative, delete_qurl, and the condition for using that instead, which gives an agent a clear routing decision.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the description adds side-effect context ('existing access sessions are closed; qURL tokens themselves are not revoked'). This goes beyond annotations by specifying exactly what is destroyed and what is preserved, though it does not detail auth requirements or potential partial failures. 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?

Four sentences, each earning its place: purpose, use-case triggers, parameter semantics, and side-effects. Front-loaded with the core action and scoped alternatives, with no redundancy or filler.

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?

Given the tool's complexity, the schema covers both parameters, annotations cover safety traits, and an output schema exists, the description fully equips an agent to call it correctly. It includes when to use, how to scope, and side-effects, with no missing critical information.

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 100% and the schema already explains the optionality of session_id ('Omit to terminate all active sessions'). The description repeats this behavior without adding new information, so it provides no incremental value beyond the schema baseline of 3.

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 states a specific verb ('Terminate') and resource ('active access sessions for a qURL resource'), clearly distinguishing it from siblings like revoke_qurl_token by explicitly noting tokens are not revoked. It also references list_qurl_sessions for inspection, reinforcing its unique role.

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?

Explicitly states when to use it ('after shortening access, rotating a link, or responding to a suspected leak') and directs the agent to use list_qurl_sessions first for inspection. It also clarifies the omission of session_id as a deliberate all-terminate behavior, effectively covering alternatives and when-not scenarios.

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

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.

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.

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.

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.

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.

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.

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

Annotations already flag this as a mutating, non-idempotent, non-destructive operation, so the description adds value by disclosing key invariants: `extend_by` and `expires_at` are mutually exclusive, at least one token update field must be set, and the operation returns the updated token summary. This goes beyond what annotations alone provide, though details like access-policy replacement semantics are only implied and left to the schema.

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 compact and front-loaded: it opens with the action and scope, then provides routing guidance, then lists constraints in a clearly labeled block. Every sentence earns its place, and the structure makes it easy for an agent to scan and act on.

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?

With eight parameters, nested access-policy objects, and a rich sibling set, the description covers the core invocation context—what to update, when to use it, which siblings to prefer, and key constraints. The output schema relieves it from detailing return values. It could have explicitly stated that `access_policy` replaces the entire policy, but the schema's field description already communicates this.

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 100%, so the baseline is 3. The description adds meaningful semantic constraints not derivable from the schema's `required` array alone—that at least one token-update field must be supplied and that `extend_by` and `expires_at` cannot be combined. It also groups the updateable fields, helping an agent understand the intent of the parameter set.

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?

Description states a precise action—'Update one qURL token under a resource'—and enumerates the mutable fields: expiration, label, access policy, max sessions, or session duration. It explicitly differentiates from siblings by contrasting with `update_qurl` and `revoke_qurl_token`, making the tool's scope unambiguous.

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?

Provides a direct when-to-use condition: 'Use this when you need to change a specific `q_…` token without changing sibling tokens or resource-level metadata.' It also names alternatives and the exact conditions that select them: use `update_qurl` for resource-level changes, and `revoke_qurl_token` when the token should stop working entirely.

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