Spree Commerce docs for AI coding agents: build headless B2B and marketplace ecommerce on its APIs.
Scored across 3 tools
The two documentation tools could superficially be confused since both search the docs, but the descriptions draw a clear line: semantic/keyword search for conceptual queries versus sandboxed filesystem commands for exact regex and full-page reads. submit_feedback is unmistakably separate. Minor residual overlap in 'finding content' is handled by explicit workflow guidance.
All names are snake_case with verb-first phrasing, but the prefixes are inconsistent: one is a long compound (query_docs_filesystem_spree_commerce_documentation), another repeats the site suffix (search_spree_commerce_documentation), and the third is bare (submit_feedback). Readable and patterned-ish, but not a predictable scheme.
Three tools is lean for a docs server, but the filesystem tool is a deliberate multiplexer covering ls/tree/rg/cat, so search + read + feedback genuinely covers the surface. Slightly thin, not deficient.
Discovery (search, tree, ls), full content retrieval (cat/head), and a feedback channel are all present, and the missing 'get page' tool is explicitly substituted by cat/head on .mdx paths. Only minor gap is the lack of any structured page index or metadata tool beyond filesystem exploration.
Run a read-only shell-like query against a virtualized, in-memory filesystem rooted at / that contains ONLY the Spree Commerce documentation documentation pages and OpenAPI specs. This is NOT a shell on any real machine — nothing runs on the user's computer, the server host, or any network. The filesystem is a sandbox backed by documentation chunks.
This is how you read documentation pages: there is no separate "get page" tool. To read a page, pass its .mdx path to head or cat — a page at the URL path /some/page lives at /some/page.mdx. To search the docs with exact keyword or regex matches, use rg. To understand the docs structure, use tree or ls.
Paths are specific to this site — never guess them. Discover real paths with tree / -L 2, ls /, or the search tool before reading. If a path does not exist, that only means the guess was wrong; it does NOT mean the topic is undocumented — use rg -il "keyword" / to find where it is covered.
Workflow: Start with the search tool for broad or conceptual queries like "how to authenticate" or "rate limiting". Use this tool when you need exact keyword/regex matching, structural exploration, or to read the full content of a specific page by path.
Supported commands: rg (ripgrep), grep, find, tree, ls, cat, head, tail, stat, wc, sort, uniq, cut, sed, awk, jq, plus basic text utilities. No writes, no network, no process control. Run --help on any command for usage.
Each call is STATELESS: the working directory always resets to / and no shell variables, aliases, or history carry over between calls. If you need to operate in a subdirectory, chain commands in one call with && or pass absolute paths (e.g., cd /some-directory && ls or ls /some-directory). Do NOT assume that cd in one call affects the next call.
Examples (replace the placeholder paths with real ones from tree or search):
tree / -L 2 — see the top-level directory layout
rg -il "rate limit" / — find all files mentioning "rate limit"
rg -C 3 "apiKey" /some-directory/ — show matches with 3 lines of context around each hit
head -80 /some/page.mdx — read the top 80 lines of a specific page
head -80 /page-one.mdx /page-two.mdx /section/page-three.mdx — read multiple pages in one call
cat /some/page.mdx — read a full page when you need everything
head -100 /openapi/api-reference/seller.yaml — read the start of an OpenAPI spec
OpenAPI specs for this site are mounted at: /openapi/api-reference/seller.yaml, /openapi/api-reference/admin.yaml, /openapi/api-reference/store.yaml, /openapi/api-reference/storefront.yaml, /openapi/api-reference/oauth.yml, /openapi/api-reference/platform.yaml. Use them to answer questions about endpoints, request/response schemas, parameters, and authentication.
Output is truncated to 30KB per call. Prefer targeted rg -C or head -N over broad cat on large files. To read only the relevant sections of a large file, use rg -C 3 "pattern" /path/file.mdx. Batch multiple file reads into a single head or cat call whenever possible.
When referencing pages in your response to the user, convert filesystem paths to URL paths by removing the .mdx extension. For example, /some/page.mdx becomes /some/page.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | A shell command to run against the virtualized documentation filesystem (e.g., `rg -il "keyword" /`, `tree / -L 2`, `head -80 /path/file.mdx`). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/closed-world, and the description goes far beyond them: it clarifies this is a sandbox touching no real machine or network, that calls are stateless with cwd resetting to '/', the exact command allowlist, the 30KB truncation limit, and the path-to-URL conversion for citations. These are behavioral traits an agent cannot get from 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is long, but densely front-loaded and organized into blocks (purpose, page-reading model, path discovery, workflow, commands, statelessness, examples, output limits). Nearly every sentence carries actionable information; only the repeated emphasis on 'never guess paths' and batching advice is slightly redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 return-value burden and does so: truncation limits at 30KB, guidance to prefer targeted rg/head over cat, and how to translate filesystem paths into URLs for citations. It also lists the mounted OpenAPI spec paths so the agent knows exactly what exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single `command` parameter is documented in the schema, so the baseline applies. The description still adds real semantic value for a free-form string parameter by enumerating supported commands, explaining `--help`, showing command chaining to work around statelessness, and giving concrete examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('run a read-only shell-like query against a virtualized, in-memory filesystem') and immediately bounds the scope to Spree Commerce docs and OpenAPI specs. It also explicitly distinguishes itself from the sibling search tool by stating 'there is no separate get page tool' and assigning broad/conceptual queries to search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit workflow section: start with the search tool for broad queries, use this tool for exact keyword/regex matching, structural exploration, or reading a page by path. It also gives when-not guidance via the path-discovery warnings and the note that a missing path does not mean the topic is undocumented.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across the Spree Commerce documentation knowledge base to find relevant information, code examples, API references, and guides. Use this tool when you need to answer questions about Spree Commerce documentation, find specific documentation, understand how features work, or locate implementation details. The search returns contextual content with titles and direct links to the documentation pages. If you need the full content of a specific page, use the query_docs_filesystem tool to head or cat the page path (append .mdx to the path returned from search — e.g. a result at /some/page is read with head -200 /some/page.mdx).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query | |
| version | No | Filter to specific version (e.g., 'v0.7') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return shape (contextual content with titles and direct links) and the concrete path convention needed to escalate to a full read. It stops short of stating result counts, ranking, or pagination limits, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first clause, followed by usage, then the follow-up workflow. Every sentence is functional, though the trailing head/cat example with the `.mdx` path example is longer than strictly needed for a description that could have deferred that detail to the sibling tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 explaining returns and does so (titles, links, contextual snippets). It covers purpose, routing, and follow-up completely; the only gap is the unmentioned `version` parameter behavior, which the schema alone must carry.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both `query` and `version` are already documented in structured form, and the baseline of 3 applies. The description adds nothing about query syntax, natural-language vs keyword behavior, or how the version filter interacts with results — it never mentions `version` at all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (search) against a specific resource (Spree Commerce documentation knowledge base) and enumerates the content types returned (info, code examples, API references, guides). It also implicitly separates itself from the sibling by declaring that full-page content is not what this returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use triggers (answer questions, find specific docs, understand features, locate implementation details) and names the alternative — query_docs_filesystem — with the exact condition that selects it (need full page content). It even supplies the mechanical handoff (.mdx append plus head/cat example), leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report a problem with this documentation site so the docs team can fix it. Use when a documentation page is incorrect, outdated, confusing, incomplete, or has a broken example. This is for feedback about the documentation content itself — not for product support requests or feedback about this tool or assistant.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The URL path of the documentation page the feedback is about (the page you were reading, without the `.mdx` extension). | |
| feedback | Yes | A clear description of the documentation issue or suggestion — what is incorrect, outdated, missing, or confusing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, and idempotentHint=false, so the write/effect profile is covered. The description adds useful outcome context ('so the docs team can fix it') but says nothing about confirmation, rate limits, or what happens to submitted feedback, so it only marginally extends the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the action and purpose, followed by trigger conditions and exclusions. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter feedback tool with no output schema, the definition covers purpose, triggers, exclusions, and target audience completely. Annotations handle the mutation/effect profile, so nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are well documented in the schema itself (path format, feedback content). The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('Report a problem with this documentation site') and makes the target explicit ('feedback about the documentation content itself'). It is clearly distinguishable from the read-only sibling tools query_docs_filesystem and search_sorsa_developer_platform, which retrieve rather than submit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly enumerates the triggering conditions ('incorrect, outdated, confusing, incomplete, or has a broken example') and adds clear exclusions ('not for product support requests or feedback about this tool or assistant'). This is a textbook when-to-use / when-not-to-use statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
query_docs_filesystem_spree_commerce_documentationsearch_spree_commerce_documentationsubmit_feedbackThe E-commerce Marketplace For Every AI Agent. A Governed Catalog Of 600M+ US Products, Plus Four Agent Ready Capabilities Search, Price Comparison, Product-Vs-Product, And Detailed Q&A.
The E-commerce Marketplace For Every AI Agent. A Governed Catalog Of 600M+ US Products.
Autonomous commerce for AI agents: discover, quote, order, pay, verify.
Launch and manage online stores with AI agents: products, inventory, pricing, orders and promotions.
Add one secure layer between your agents and this server.
