SpellBook Finance

spellbook_pricing_decision_explain

Read-onlyIdempotent

Read one seller listing's recorded pricing evidence for one marketplace. Returns the last recorded ask, market anchor, safe price effect, decision timestamps and whether the evidence is observed, recorded, projected or missing. Call this when a seller asks what price was saved or what evidence supports it, then use the seller controls tools when they want to inspect or change a setting. It never claims a remote marketplace ask is current without a remote observation timestamp. Separately timestamped performance pools this workspace card across editions and finishes and reports sampled exposure, sales, uncertainty and gaps; it does not recompute the saved price.

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": {
      "workspaceId": "<workspaceId>",
      "itemId": "<itemId>",
      "channel": "<channel>"
    },
    "name": "spellbook_pricing_decision_explain"
  }
}

Input Schema

Name	Required	Description
`itemId`	Yes	The exact Item id, from a prior spellbook_inventory_items_query. Required.
`channel`	Yes	Which marketplace listing to explain. Required, because the same copy carries a different ask per channel.
`context`	No	Optional analytics context: briefly describe the user's underlying goal in one sentence. Do not copy prompts, personal details, credentials, identifiers, or tool arguments. Omit for private tasks.
`workspaceId`	Yes	The workspace that owns the listing. Required.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 26, 2026

addedInput schema / properties / context

Added value: +{
+  "description": "Optional analytics context: briefly describe the user's underlying goal in one sentence. Do not copy prompts, personal details, credentials, identifiers, or tool arguments. Omit for private tasks.",
+  "maxLength": 512,
+  "type": "string"
+}

First observedSep 25, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld, so credit goes to the added context: evidence status categories (observed, recorded, projected, missing), the staleness guarantee that a remote ask is never claimed current without a remote observation timestamp, and the explicit note that it does not recompute the saved price. That is genuine behavioral disclosure beyond the annotations.

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

Conciseness3/5

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

The core purpose and evidence list are front-loaded, but the final sentence is a confusing run-on ('performance pools this workspace card across editions and finishes') that appears to describe different functionality and is not clearly tied to this tool's output. It adds length without adding usable meaning for an agent.

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

Completeness3/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 does its job of enumerating return values and evidence states. However, the stray performance-pool sentence creates ambiguity about scope, and nothing is said about how much history or how many timestamps are returned, leaving the agent uncertain whether it also returns aggregate performance data.

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 description coverage is 100% and all four parameters are documented in-schema, including the channel enum rationale and itemId provenance. The description only echoes the marketplace-scoping notion ('one marketplace') without adding parameter-level meaning, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a specific verb and resource: read one listing's recorded pricing evidence for one marketplace, and enumerates the returned evidence fields (last recorded ask, market anchor, safe price effect, timestamps, evidence status). It is distinguishable from sibling read tools, though the final sentence introduces a second block of subject matter (performance pools across editions/finishes) that muddies what the tool actually returns.

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 says when to call it ('when a seller asks what price was saved or what evidence supports it') and routes follow-up intent to the seller controls tools for inspecting or changing a setting. No explicit when-not-to-call or named alternative among the many pricing siblings (e.g. spellbook_sku_price_controls, pricing_amendment_get), so it falls 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.

All SpellBook Finance 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.

Resources

Need Help?