Skip to main content
Glama
Sign In

Ptally

by ai.ptally
OverviewDiscussionsAdmin

Amend a quote

amend_quote

Amend a SAVED quote (a quote_reference from get_quotes): its price (result), and optionally valid or sold, with a required reason. Logged in the quote's audit trail under the signed-in user, with the time, the old and new values, source "mcp" and the reason. The engine's own result, valid and output are never changed — the amended values sit beside them, and setting price or validity back to the engine's value clears that amendment (still logged).

BEFORE CALLING

  1. Call get_quote (or get_quotes) for the quote's current price, validity and sold flag.

  2. Tell the user exactly what will change (old → new) and the reason that will be logged, and get their go-ahead.

RULES

  • At least one of result, valid, sold, and each must differ from what the quote is now (else an error says nothing changed).

  • result is a number; valid and sold are booleans; reason is a non-empty sentence.

  • A sold quote is locked. The only change it accepts is sold: false on its own (marking it unsold, with a reason); after that it can be amended and marked sold again — three calls, each logged. Check get_quote first, and tell the user when a change means unselling the quote. A price change can go in the same call that marks it sold.

  • Refused in read-only mode.

RESULT { quote_reference, engine: { result, valid }, now: { result, valid, sold }, amended, logged: { amendment_reference, by, at, source, result: { from, to }, valid, sold, reason }, quote_url, next_steps }.

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": {
      "quote_reference": "<quote_reference>",
      "reason": "<reason>"
    },
    "name": "amend_quote"
  }
}

Input Schema

NameRequiredDescriptionDefault
soldNoOptional. true marks it sold and locks it (a price change can go in the same call). false, sent on its own, marks a sold quote unsold so it can be changed.
validNoOptional. Whether the quote is now valid. Only on a quote that isn't sold.
reasonYesRequired on every call: why the price (or validity, or sale) is changing, in the user's words, e.g. "Quote amendment: agreed 5% discount". Logged with the change, who made it and when.
resultNoThe new price. Only on a quote that isn't sold — mark a sold quote unsold first.
quote_referenceYesThe saved quote to amend, from get_quotes.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.7/5.0
Behavior4/5

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

Goes well beyond the annotations by disclosing the audit trail contents (old/new values, user, time, source 'mcp', reason), the non-destructive amendment model where engine values sit beside amendments, and the clearing semantics when reverting to the engine value. The sold-quote lock and its three-call unsell/resell path are behavior an agent could not infer from destructiveHint=false alone.

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 purpose, then clearly sectioned into BEFORE CALLING, RULES and RESULT, which makes a long description scannable. A few clauses (e.g. the three-call unselling aside) are dense but each carries operational detail an agent needs, so there is little true waste.

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?

Even without an output schema, the RESULT block spells out the returned shape including engine vs now values, amendment logging and next_steps. Combined with the preconditions and the mutation rules, an agent has everything needed to call this correctly on the first attempt.

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

Parameters5/5

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

Schema coverage is already 100%, so the baseline is 3, but the description adds genuine cross-parameter meaning: at least one of result/valid/sold must be supplied and differ from current state, types are restated, and the sold lock constrains which of result/valid may accompany which call. That interaction logic is not derivable from any single property description.

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 and resource ('Amend a SAVED quote'), names its identifier source (quote_reference from get_quotes), and enumerates the exact fields it can change. It also implicitly separates itself from run_quote by declaring the engine's own result/valid/output are never touched.

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?

Provides an explicit BEFORE CALLING sequence (fetch current state, confirm old → new and reason with the user), an at-least-one-field-must-differ rule, and a named alternative workflow for locked sold quotes. It also states a hard precondition (refused in read-only mode), so an agent knows both when to call and when the call will fail.

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

All Ptally toolsInspect
Try in Browser
Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources