SpellBook Finance

spellbook_inventory_items_query

Read-onlyIdempotent

Read one private page of existing physical Items matching an exact acquisition source, exact bins, or printing, finish and condition groups. Coordinate filters narrow source or group results. Each Item carries scanPlacement, its approximate position in its scanned bin as ordinal of total, or null when it was never scanned there.

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

Input Schema

Name	Required	Description
`bins`	No	Restrict results to these exact bin names, up to 25. Omit to search every bin.
`limit`	No	Maximum Items to return, 1 to 1000. Omit for the default of 20.
`cursor`	No	Opaque cursor from a previous page, passed back unchanged. Omit to start from the first page.
`groups`	No	Restrict results to these exact printing, finish and condition groups, up to 25. Omit to skip this filter.
`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 to read Items from. Required.
`acquisitionSource`	No	Restrict results to one exact acquisition source, such as a bulk-import ID. Combine with bins or groups to narrow it further.

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

Changed1 schema field changedOct 10, 2026

addedInput schema / properties / acquisitionSource

Added value: +{
+  "description": "Restrict results to one exact acquisition source, such as a bulk-import ID. Combine with bins or groups to narrow it further.",
+  "maxLength": 120,
+  "minLength": 1,
+  "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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: results are a single private page, filters are exact-match rather than fuzzy, and each Item carries scanPlacement as an ordinal-of-total with a null case for never-scanned items.

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?

Three sentences, front-loaded with what the tool reads and followed by filter behavior and a return-field note. Dense but every clause carries information; minor cost is that the filter clause is compressed enough to require a second read.

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 7-parameter read tool with full schema coverage and no output schema, the description covers pagination concept ('one private page'), filter semantics, and the non-obvious scanPlacement return field. It stops short of explaining how filters combine when multiple are supplied, which is the remaining ambiguity.

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%, so every parameter already has documentation, including limit, cursor and the groups object. The description reinforces 'exact' matching and filter narrowing but adds no syntax or format detail beyond the schema, so the baseline of 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?

States a specific verb and resource ('Read one private page of existing physical Items') and enumerates the filter axes: exact acquisition source, exact bins, and printing/finish/condition groups. It is clear what the tool returns, but it never names a sibling (e.g. spellbook_inventory_holdings or spellbook_inventory_incoming) to disambiguate which inventory read to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Coordinate filters narrow source or group results' gives partial guidance on how filters interact, implying it is the query tool for filtered lookups. However, there is no explicit when-to-use versus alternative tools, nor any note on when a filter combination is invalid or redundant.

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?