clm_get_contract_document_download_urlGet a short-lived original/available preview-PDF URL; default: current primary. Supports prior/draft/related versions.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ID | |
| fileId | No | File version ID; omit for current primary | |
| variant | No | Retained original or available preview PDF | original |
Changes observed during successful MCP inspections.
Input schema / properties / fileId / descriptionPrevious value: -"Contract file version identifier. Omit to download the current primary version."New value: +"File version ID; omit for current primary"Input schema / properties / fileId / patternRemoved value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"Input schema / properties / id / descriptionPrevious value: -"Contract identifier"New value: +"ID"Input schema / properties / id / patternRemoved value: -"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"Input schema / properties / variant / descriptionPrevious value: -"Original retained file or the available preview PDF"New value: +"Retained original or available preview PDF"Output schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "contractId": {
- "allOf": [
- {
- "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
- "type": "string"
- },
- {
- "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
- "type": "string"
- }
- ],
- "description": "Contract UUID",
- "type": "string"
- },
- "downloadUrl": {
- "description": "Short-lived HTTPS URL for the selected document bytes",
- "minLength": 1,
- "type": "string"
- },
- "expiresAt": {
- "allOf": [
- {
- "pattern": "^(?:(?:\\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))$",
- "type": "string"
- },
- {
- "pattern": "^(?:(?:\\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))$",
- "type": "string"
- }
- ],
- "description": "When the signed URL stops working (ISO-8601)",
- "type": "string"
- },
- "expiresIn": {
- "description": "Number of seconds until the signed URL expires",
- "exclusiveMinimum": 0,
- "maximum": 9007199254740991,
- "type": "integer"
- },
- "fileId": {
- "allOf": [
- {
- "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
- "type": "string"
- },
- {
- "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
- "type": "string"
- }
- ],
- "description": "Contract file version UUID",
- "type": "string"
- },
- "fileName": {
- "description": "Download file name",
- "minLength": 1,
- "type": "string"
- },
- "isPrimary": {
- "description": "Whether the file belongs to the primary document group",
- "type": "boolean"
- },
- "mimeType": {
- "description": "MIME type of the selected bytes",
- "minLength": 1,
- "type": "string"
- },
- "status": {
- "enum": [
- "draft",
- "effective",
- "superseded"
- ],
- "type": "string"
- },
- "variant": {
- "enum": [
- "original",
- "preview"
- ],
- "type": "string"
- }
- },
- "required": [
- "downloadUrl",
- "expiresAt",
- "expiresIn",
- "fileName",
- "mimeType",
- "variant",
- "isPrimary",
- "status",
- "fileId",
- "contractId"
- ],
- "type": "object"
-}New value: +nullDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the bar is lower. The description's one genuine addition is 'short-lived', which tells the agent the URL expires and shouldn't be cached — useful, but no expiry scale, auth prerequisites, or redirect behavior are 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?
Two compact clauses with the core capability front-loaded and no filler. It is slightly telegraphic — 'original/available preview-PDF URL' takes a second read to parse.
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 simple three-parameter read with strong annotations and no output schema, the description covers the returned artifact (a short-lived URL), the default version, and which versions are reachable. Only prerequisite/auth context is missing, which is minor here.
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 schema already documents id, fileId and the variant enum with defaults. The description echoes the same semantics ('omit for current primary', original vs available preview) without adding format or constraint detail beyond the schema, so it sits at the baseline.
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 ('Get a ... download URL') and pins down scope with 'default: current primary' and coverage of prior/draft/related versions. That distinguishes it from siblings like clm_read_contract_document or clm_search_contract_documents, though it never names an alternative explicitly.
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 implies when to use it via the default behavior (omit fileId for current primary; pass a version for prior/draft/related), which is real selection guidance. It gives no explicit when-not-to-use or routing to a sibling tool such as clm_read_contract_document for in-band content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.