clm_add_contract_documentsAdd drafts/related documents or replace the effective primary on an editable contract. No Parser credits.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ID | |
| documents | Yes | Intent-only sources; at most one replace per request. | |
| allowDuplicate | No | Allow duplicate linked document. | |
| idempotencyKey | Yes | Retry key for this exact request |
Changes observed during successful MCP inspections.
Input schema / properties / allowDuplicate / descriptionPrevious value: -"Set to true only after the user has been told the document is already associated with a contract and has asked for it to be added anyway."New value: +"Allow duplicate linked document."Input schema / properties / documents / descriptionPrevious value: -"Intent-only document sources. Submit at most one replace document per request."New value: +"Intent-only sources; at most one replace per request."Input schema / properties / documents / items / oneOfPrevious value: -[
- {
- "additionalProperties": false,
- "properties": {
- "dataBase64": {
- "maxLength": 25690112,
- "minLength": 4,
- "type": "string"
- },
- "fileName": {
- "maxLength": 120,
- "minLength": 1,
- "type": "string"
- },
- "intent": {
- "enum": [
- "draft",
- "related",
- "replace"
- ],
- "type": "string"
- },
- "kind": {
- "const": "inline",
- "type": "string"
- },
- "mimeType": {
- "maxLength": 120,
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "intent",
- "kind",
- "fileName",
- "mimeType",
- "dataBase64"
- ],
- "type": "object"
- },
- {
- "additionalProperties": false,
- "properties": {
- "downloadUrl": {
- "format": "uri",
- "type": "string"
- },
- "expiresAt": {
- "format": "date-time",
- "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"
- },
- "fileName": {
- "maxLength": 120,
- "minLength": 1,
- "type": "string"
- },
- "fileSize": {
- "exclusiveMinimum": 0,
- "maximum": 2147483647,
- "type": "integer"
- },
- "intent": {
- "enum": [
- "draft",
- "related",
- "replace"
- ],
- "type": "string"
- },
- "kind": {
- "const": "remote",
- "type": "string"
- },
- "mimeType": {
- "maxLength": 120,
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "intent",
- "kind",
- "fileName",
- "mimeType",
- "fileSize",
- "downloadUrl"
- ],
- "type": "object"
- }
-]New value: +[
+ {
+ "additionalProperties": false,
+ "properties": {
+ "dataBase64": {
+ "maxLength": 52953088,
+ "minLength": 4,
+ "type": "string"
+ },
+ "fileName": {
+ "maxLength": 120,
+ "minLength": 1,
+ "type": "string"
+ },
+ "intent": {
+ "enum": [
+ "draft",
+ "related",
+ "replace"
+ ],
+ "type": "string"
+ },
+ "kind": {
+ "const": "inline",
+ "type": "string"
+ },
+ "mimeType": {
+ "maxLength": 120,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "intent",
+ "kind",
+ "fileName",
+ "mimeType",
+ "dataBase64"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "downloadUrl": {
+ "format": "uri",
+ "type": "string"
+ },
+ "expiresAt": {
+ "format": "date-time",
+ "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"
+ },
+ "fileName": {
+ "maxLength": 120,
+ "minLength": 1,
+ "type": "string"
+ },
+ "fileSize": {
+ "exclusiveMinimum": 0,
+ "maximum": 2147483647,
+ "type": "integer"
+ },
+ "intent": {
+ "enum": [
+ "draft",
+ "related",
+ "replace"
+ ],
+ "type": "string"
+ },
+ "kind": {
+ "const": "remote",
+ "type": "string"
+ },
+ "mimeType": {
+ "maxLength": 120,
+ "minLength": 1,
+ "type": "string"
+ }
+ },
+ "required": [
+ "intent",
+ "kind",
+ "fileName",
+ "mimeType",
+ "fileSize",
+ "downloadUrl"
+ ],
+ "type": "object"
+ }
+]Input schema / properties / id / descriptionPrevious value: -"Existing 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 / idempotencyKey / descriptionPrevious value: -"Stable retry key for this exact document request"New value: +"Retry key for this exact request"Output schema / (root)Previous value: -{
- "$schema": "http://json-schema.org/draft-07/schema#",
- "additionalProperties": false,
- "properties": {
- "documents": {
- "items": {
- "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": "Existing contract UUID",
- "type": "string"
- },
- "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": "Created contract file version UUID",
- "type": "string"
- },
- "intent": {
- "enum": [
- "draft",
- "related",
- "replace"
- ],
- "type": "string"
- },
- "processingState": {
- "enum": [
- "not_queued",
- "queued"
- ],
- "type": "string"
- },
- "role": {
- "enum": [
- "primary",
- "related"
- ],
- "type": "string"
- },
- "status": {
- "enum": [
- "draft",
- "effective"
- ],
- "type": "string"
- }
- },
- "required": [
- "contractId",
- "fileId",
- "intent",
- "role",
- "status",
- "processingState"
- ],
- "type": "object"
- },
- "type": "array"
- }
- },
- "required": [
- "documents"
- ],
- "type": "object"
-}New value: +nullDoes the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is known. The description adds genuinely new context: 'replace the effective primary' identifies what is affected, and 'No Parser credits' discloses a cost trait absent from annotations. It still omits what happens to the superseded primary (deleted vs. archived) and how the idempotency key governs retries.
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, front-loaded with the action and its scope, with zero filler. The trailing 'No Parser credits' is useful but is unexpanded jargon that a reader may need to interpret.
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?
This is a destructive mutation with three required parameters and no output schema, so the description must carry the behavioral burden that annotations only partially cover. It is adequate on intent and cost, but silent on payload limits (inline base64 vs. remote downloadUrl), what the caller gets back, and the consequence of replacing a primary document.
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 a 3 is the baseline, but the description adds meaning the schema does not: it maps the bare 'draft'/'related'/'replace' enum to intent semantics and ties 'replace' specifically to the effective primary of an editable contract. It says nothing extra about idempotencyKey or allowDuplicate, which the schema already documents.
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 a specific verb (Add / replace) and resource (contract documents) plus the three intents: draft, related, and replacing the effective primary. It also bounds the target to an 'editable contract'. It does not, however, distinguish this from nearby siblings like clm_create_upload_url, clm_create_upload_session, or clm_ingest_contract, which an agent could plausibly confuse with it.
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 phrase 'on an editable contract' is a real precondition, and 'No Parser credits' hints at a cost profile that may steer an agent away from reprocessing tools. But there is no explicit when-to-use versus when-not guidance and no named alternative for remote vs. inline uploads or for starting a new document ingestion.
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.