Ferret

Add or change a warranty

save_warranty

Records a warranty on an item — who stands behind it, when cover starts and ends, what it covers — or, with id, changes one (it was extended, a date was wrong).

Instructions

Records a warranty on an item — who stands behind it, when cover starts and ends, what it covers — or, with id, changes one (it was extended, a date was wrong). To add: itemId and endsOn; use it when the person tells you about one, or to accept a warranty the vision model read off a receipt or warranty card (get_item's suggestions) once the person has confirmed it — pass that document's id as attachmentId. Check get_item first so you don't add one twice. To change: fields left out stay as they are; null clears one. A warranty can't end before it starts. Warranties ending within 30 days show in what_needs_attention. Returns the warranty with its id and status.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "save_warranty"
  }
}

Input Schema

Name	Required	Description
`id`	No	The warranty to change, from get_item or list_warranties; leave out to add a new one
`notes`	No	Anything else: how to claim, the registration number
`endsOn`	No	When cover ends, yyyy-mm-dd
`itemId`	No	To add: the item's id, from search_inventory
`coverage`	No	What it covers: "parts and labour", "accidental damage"
`provider`	No	Who stands behind it: "Bosch", "Best Buy Geek Squad"
`startsOn`	No	When cover began, yyyy-mm-dd (usually the purchase date)
`attachmentId`	No	The receipt or warranty card it came from: a document's id from get_item

Schema Changelog

Changes observed during successful MCP inspections.

Addedv2026.11.10Nov 9, 2026

TDQS

A4.2/5.0

Behavior3/5

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

Annotations already declare a non-read-only, non-destructive, closed-world write, and the description adds genuinely useful behavior beyond them: partial-update semantics ('fields left out stay as they are; null clears one'), a validation rule ('A warranty can't end before it starts'), a downstream side effect (expiring warranties surface in what_needs_attention), and the return shape (warranty with id and status). What it omits is who may perform the write, whether a change is reversible, and what happens if itemId is unknown; given annotations cover the safety profile, this sits at a solid adequate-but-not-rich level.

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-loads the add/change split, then prerequisites, then edit semantics, then validation and side effects — a sensible ordering with little waste. It is dense and slightly long for a single paragraph, with nested parentheticals ('get_item's suggestions', 'it was extended, a date was wrong') that slow parsing, but each clause carries information.

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?

For an 8-parameter write tool with no output schema, the description covers the missing pieces an agent needs: required combination for creation, partial-update and null-clearing behavior, a cross-field constraint, the prerequisite lookup, a downstream visibility effect, and the return value. Nothing essential for a correct invocation is left to inference.

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 coverage is 100% and every parameter is already documented, so the baseline is 3. The description does add one thing the schema cannot express — that adding requires itemId plus endsOn (the schema marks zero required parameters) and that attachmentId should carry the source document's id — but it does not explain the add-vs-change interaction of individual fields or any format details beyond the schema.

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?

Opens with a concrete verb+resource ('Records a warranty on an item') and immediately distinguishes the two modes: add when 'id' is absent, change when 'id' is supplied. The subject matter (provider, cover start/end, coverage scope) is spelled out, so an agent can tell it apart from siblings like save_warranty_claim or save_provider without opening the schema.

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?

Gives explicit when-to-use triggers ('when the person tells you about one', 'to accept a warranty the vision model read off a receipt ... once the person has confirmed it'), names the upstream sibling to consult (get_item's suggestions), and states a negative guard ('Check get_item first so you don't add one twice'). Alternatives and preconditions are both covered.

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