Skip to main content
Glama
karnameh-mcp

karnameh-mcp

by sepehr071

New-car price history

kn_price_history
Read-onlyIdempotent

Retrieve daily average market price history for a new-car variant by production year, and optionally list each source's current quote for a chosen year.

Instructions

Get the daily average market price history of one new-car variant, per production year.

Use after kn_price_list or kn_latest_prices. With year, also lists each source's current quote.

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": {
      "name": "<name>"
    },
    "name": "kn_price_history"
  }
}

Input Schema

NameRequiredDescriptionDefault
daysNoLatest daily points per year.
nameYesExact English `name` from kn_price_list or kn_latest_prices, e.g. 'Peugeot 207i Manual TU5P'.
yearNoProduction year (Persian). Omit for all.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.2.0
    • changedInput schema / properties / days / description
      Previous value: -"How many of the latest daily points to return per year (1-90)."New value: +"Latest daily points per year."
    • changedInput schema / properties / name / description
      Previous value: -"Exact English model-variant name from kn_price_list (`name`), e.g. 'Peugeot 207i Manual TU5P'."New value: +"Exact English `name` from kn_price_list or kn_latest_prices, e.g. 'Peugeot 207i Manual TU5P'."
    • removedInput schema / properties / year / anyOf
      Removed value: -[
      -  {
      -    "maximum": 1450,
      -    "minimum": 1380,
      -    "type": "integer"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • changedInput schema / properties / year / description
      Previous value: -"Production year (Persian). Omit for every year."New value: +"Production year (Persian). Omit for all."
    • addedInput schema / properties / year / maximum
      Added value: +1450
    • addedInput schema / properties / year / minimum
      Added value: +1380
    • addedInput schema / properties / year / type
      Added value: +[
      +  "integer",
      +  "null"
      +]
  2. First observedv0.1.1

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact — that supplying `year` also returns each source's current quote — but says nothing about data freshness, currency/units, or gaps in history for a variant.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both earning their place: the first defines the output, the second covers prerequisite and the conditional behavior. The core purpose is front-loaded with no filler.

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?

With no output schema, the description carries the burden of describing returns, and it does specify daily averages per production year plus source quotes when `year` is set. It stops short of indicating units/currency or whether sparse days mean missing data, which matters for a time-series tool.

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 earns above that by explaining the conditional side effect of `year` (also lists each source's current quote), which the schema does not convey. `days` and `name` are left entirely to the schema, which is acceptable given full coverage.

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 ('daily average market price history of one new-car variant') plus the granularity ('per production year'), which cleanly separates it from sibling lookups like kn_price_list and kn_latest_prices that return current prices rather than history.

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 an explicit prerequisite chain ('Use after kn_price_list or kn_latest_prices'), which tells the agent it needs an exact variant name obtained elsewhere first. It does not state when to avoid this tool (e.g., for current-only pricing), 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.