Workspace369

Update a draft proposal

proposals_update_draft

Destructive

Edit an existing draft proposal by proposal_id (proposals_create_draft makes a new one). Only drafts are editable: a sent, accepted or declined proposal is refused (recall a sent one to draft with proposals_update_status or in the app), and an accepted or deposit-paid proposal is locked and changes only through a change order in the app. Changeable: title, internal notes (replaced), add_line_items (same grammar as proposals_create_draft; repeating them adds the lines twice), remove_line_items (by line name), discount (discount_percent or discount_amount; 0 removes it), signature requirement, deposit (deposit_percent or deposit_amount; require_deposit: false removes it) and expiry (valid_for_days; 0 removes it). When lines, discount or deposit change, subtotal, tax, total and deposit are re-derived server-side; other edits leave the money unchanged. It cannot send, accept, decline, convert, delete, change the client or tax rate, or edit layout, theme or sections (see proposals_update_design, proposals_edit_sections).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "proposal_id": "<proposal_id>"
    },
    "name": "proposals_update_draft"
  }
}

Input Schema

Name	Required	Description
`notes`	No	Replaces the internal notes.
`title`	No	New title.
`proposal_id`	Yes	Draft proposal id (from proposals_create_draft or proposals_search).
`add_line_items`	No	Lines to add: {product_id, quantity} or {description, unit_price, quantity}.
`deposit_amount`	No	Deposit as a fixed amount.
`valid_for_days`	No	Days until the proposal expires; 0 removes the expiry.
`deposit_percent`	No	Deposit as a percentage of the total. Use this or `deposit_amount`.
`discount_amount`	No	Discount as a fixed amount; 0 removes it.
`require_deposit`	No	false removes the deposit requirement.
`discount_percent`	No	Discount as a percentage; 0 removes it. Use this or `discount_amount`.
`remove_line_items`	No	Line names to remove.
`require_signature`	No	Whether accepting requires a signature.

Output Schema

Name	Required	Description	Default
`changed`	Yes
`changes`	No
`proposal`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 21, 2026

changedInput schema / properties / proposal_id / description

Previous value: -"Draft proposal id."New value: +"Draft proposal id (from proposals_create_draft or proposals_search)."

First observedOct 21, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already indicate a destructive, non-idempotent write, but the description adds substantial behavior: locked proposal states, server-side re-derivation of subtotal/tax/total/deposit when lines or money fields change, and the warning that repeating add_line_items adds lines twice. It also clarifies that other edits leave money unchanged.

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?

The description is dense but front-loaded, leading with the editable resource and state restrictions before enumerating fields. It is long, but most sentences carry necessary operational detail; a slightly more structured enumeration would improve scanability.

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?

Given 12 parameters, a rich input schema, annotations, and an output schema, the description is complete enough to call the tool correctly. It covers state preconditions, mutation scope, recalculation behavior, and sibling routing without needing to explain return values.

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 coverage is 100%, so the baseline is 3. The description adds useful meaning beyond the schema: add_line_items uses the same grammar as proposals_create_draft, repeating items adds them twice, remove_line_items is by line name, and zero values remove discount/deposit/expiry. The only minor gap is that it does not restate every parameter constraint, but it compensates well overall.

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 states a specific verb and resource ('Edit an existing draft proposal by proposal_id') and immediately distinguishes it from proposals_create_draft and from status/design/section siblings. An agent can identify exactly what this tool mutates and what it does not.

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?

It gives explicit when-to-use and when-not-to-use rules: only drafts are editable, sent proposals must be recalled via proposals_update_status or the app, accepted/deposit-paid proposals are locked to change orders, and design/section/client/tax edits belong to other tools. Alternatives are named directly.

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

All Workspace369 tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.