dealdesk-mcp

dealdesk.create_card

Create a desk card with title, stage, owner, priority, customer links, and deal estimates to track opportunities on the desk.

Instructions

Create a desk card (title, stage, optional description, ownerUserId, priority, Customer Directory company/contact, and optional deal estimates: estimatedValue, estimatedValueCurrency, estimatedValuePeriod, probabilityPercent). Resolve owners with dealdesk.list_desk_users. Prefer estimate fields over create_case when the opportunity already lives on the desk.

Input Schema

Name	Required	Description
`notes`	No	Deprecated alias for description — prefer description
`stage`	No	Desk board column id (not a UI label). Resolve with dealdesk.list_desk_stages. Default board: request, request-in-progress, quote-preparation, quote-sent, quote-accepted, order-processing, order-completed, closed. Soft-close with closed. Never invent ids by slugifying labels (e.g. Anfrage in Bearbeitung → request-in-progress, not anfrage-in-bearbeitung).
`title`	Yes
`priority`	No	Card priority label (default normal; free text as shown on the desk).
`companyId`	No	Customer Directory company id → accountRef on the card
`contactId`	No	Customer Directory contact id → contactRef on the card
`projectId`	No	DealDesk project id. Omit when the OAuth token or API key authorizes exactly one project. Required when Connect authorized several projects.
`description`	No	Card description (main body text shown on the card)
`ownerUserId`	No	Desk owner user id from dealdesk.list_desk_users
`estimatedValue`	No	Working forecast amount. Does not rewrite linked quote totals.
`deskDescription`	No	Local desk-only description (optional; distinct from CRM case description)
`probabilityPercent`	No	Win chance percent (0–100).
`estimatedValuePeriod`	No	Labels estimatedValue as one-time, monthly, or yearly. Does not convert the amount. Use year for ARR / per-year (e.g. 4000 EUR per year). Defaults to one_time when omitted on create.
`estimatedValueCurrency`	No	ISO 4217 alpha-3 currency code (e.g. EUR).

Output Schema

Name	Required	Description	Default
`card`	Yes	Desk card. Null owner/account fields are omitted so hosts that cached an older object-only schema still accept the payload.

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedv0.1.1Oct 7, 2026

addedInput schema / properties / estimatedValue

Added value: +{
+  "description": "Working forecast amount. Does not rewrite linked quote totals.",
+  "minimum": 0,
+  "nullable": true,
+  "type": "number"
+}

addedInput schema / properties / estimatedValueCurrency

Added value: +{
+  "description": "ISO 4217 alpha-3 currency code (e.g. EUR).",
+  "type": "string"
+}

addedInput schema / properties / estimatedValuePeriod

Added value: +{
+  "description": "Labels estimatedValue as one-time, monthly, or yearly. Does not convert the amount. Use year for ARR / per-year (e.g. 4000 EUR per year). Defaults to one_time when omitted on create.",
+  "enum": [
+    "one_time",
+    "month",
+    "year"
+  ],
+  "type": "string"
+}

addedInput schema / properties / ownerUserId

Added value: +{
+  "description": "Desk owner user id from dealdesk.list_desk_users",
+  "type": "string"
+}

addedInput schema / properties / priority

Added value: +{
+  "description": "Card priority label (default normal; free text as shown on the desk).",
+  "type": "string"
+}

addedInput schema / properties / probabilityPercent

Added value: +{
+  "description": "Win chance percent (0–100).",
+  "maximum": 100,
+  "minimum": 0,
+  "nullable": true,
+  "type": "number"
+}

changedInput schema / properties / projectId / description

Previous value: -"DealDesk project id (must match API key / OAuth project)"New value: +"DealDesk project id. Omit when the OAuth token or API key authorizes exactly one project. Required when Connect authorized several projects."

addedInput schema / properties / stage / description

Added value: +"Desk board column id (not a UI label). Resolve with dealdesk.list_desk_stages. Default board: request, request-in-progress, quote-preparation, quote-sent, quote-accepted, order-processing, order-completed, closed. Soft-close with closed. Never invent ids by slugifying labels (e.g. Anfrage in Bearbeitung → request-in-progress, not anfrage-in-bearbeitung)."

changedInput schema / required

Previous value: -[
-  "projectId",
-  "title"
-]New value: +[
+  "title"
+]

changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```

changedOutput schema / properties / card / description

Previous value: -"Desk card shown in the card-summary widget"New value: +"Desk card. Null owner/account fields are omitted so hosts that cached an older object-only schema still accept the payload."

removedOutput schema / properties / card / properties

Removed value: -{
-  "accountRef": {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  "attributes": {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  "cardId": {
-    "type": "string"
-  },
-  "contactRef": {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  "description": {
-    "type": "string"
-  },
-  "deskDescription": {
-    "type": "string"
-  },
-  "notes": {
-    "type": "array"
-  },
-  "ownerDeskUser": {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  "ownerRef": {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  "priority": {
-    "type": "string"
-  },
-  "stage": {
-    "type": "string"
-  },
-  "title": {
-    "type": "string"
-  }
-}

First observedv0.1.0Sep 30, 2026

TDQS

A3.6/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full behavioral burden, yet it discloses none of the mutation profile: no permissions/auth requirements, no idempotency or duplicate-handling, no notification or side-effect behavior, and no statement that the deprecated 'notes' alias should be avoided. The only behavioral hint is the create_case routing preference, which is thin for a 14-param write tool.

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?

Front-loaded with the core action and the key routing rule, packed into two dense sentences with no filler. The long parenthetical enumeration of fields is slightly heavy but each item maps to a parameter, so little is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values need not be described, and the schema covers parameter detail thoroughly. However, for a mutation tool with zero annotations, the description omits the authorization and side-effect context an agent needs to call it safely, leaving a meaningful gap.

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

Parameters3/5

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

Schema description coverage is 93%, so the schema already documents nearly every parameter with richer detail (stage id rules, currency format, period conversion notes). The description's parenthetical field list largely restates schema content and adds no syntax or format meaning beyond it, which is the baseline-3 case.

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?

States a specific verb+resource ('Create a desk card') and enumerates the fields it accepts, so the agent knows exactly what the operation produces. It also distinguishes itself from the sibling create_case by preference rule, letting an agent route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives actionable context: resolve owners via dealdesk.list_desk_users and prefer estimate fields over create_case when the opportunity already lives on the desk. It names one alternative with a selecting condition, but provides no explicit when-not guidance or prerequisites for card creation itself.

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

Deploy Server