Ferret

File or update a warranty claim

save_warranty_claim

Instructions

Records a claim under one of an item's warranties — what went wrong, the provider's claim number (reference), its status (filed by default, today by default) — or, with id, updates one when the person hears back: status (filed, in_progress, approved, denied, resolved), the resolution, what it cost (cents). To file: warrantyId (from get_item) and the problem. Closing it (denied or resolved) dates it today unless resolvedOn is given. Claims with no news for two weeks show in what_needs_attention. Returns the claim with its id.

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_claim"
  }
}

Input Schema

Name	Required	Description
`id`	No	The claim to change, from get_item; leave out to add a new one
`notes`	No	Anything else: calls made, who said what
`status`	No	Where it stands: filed, in_progress, approved, denied or resolved
`filedOn`	No	When the claim was made, yyyy-mm-dd; today if left out
`problem`	No	What went wrong, in the person's words
`costCents`	No	What the household paid out of pocket, in cents
`reference`	No	The provider's claim or case number
`resolution`	No	How it ended: repaired, replaced, refunded…
`resolvedOn`	No	When it was closed, yyyy-mm-dd
`warrantyId`	No	To file: the warranty's id, from get_item

Schema Changelog

Changes observed during successful MCP inspections.

Addedv2026.11.10Nov 9, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations only declare the safety profile (not read-only, not destructive, closed-world), so the description carries real weight and delivers: server-side defaults (status filed, filedOn today), an implicit side effect (closing as denied/resolved stamps today unless resolvedOn is given), and the return value ('returns the claim with its id'). It also routes the agent to what_needs_attention for stale claims.

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 core action, then the update path, then filing instructions, with no filler sentences. The heavy em-dash parentheticals make a couple of clauses hard to parse on first read, which costs it a point.

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

Completeness4/5

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

For a 10-parameter create/update tool with no output schema, the description covers both modes, defaults, closing behavior, and the return shape. The gap is behavior with zero required parameters — it never says what happens if both id and warrantyId are omitted.

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 baseline would be 3; the description adds conditional semantics the schema cannot express — that warrantyId+problem are what a filing needs, and that resolvedOn only matters for closing statuses. It does not address the unusual case of calling with neither id nor warrantyId.

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 pair (records a claim under an item's warranty; updates one with id) and enumerates the fields involved. An agent can tell it apart from save_warranty and other save_* siblings because the description makes clear this is the claim record, not the warranty itself.

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?

Explicitly splits the two modes: 'To file: warrantyId (from get_item) and the problem' versus 'with id, updates one when the person hears back', and points at get_item for id sourcing. It does not name any sibling tool as an alternative or exclusion, which keeps it short of a 5.

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