Skip to main content
Glama

sb_api_call

Destructive

Call Store Builder API operations by catalog ID or custom method and path; dry-run by default lets you inspect responses, select fields, and limit list items before sending changes.

Instructions

Call an operation from sb_api_find (id), or a route the catalog lacks (method+path); dry run by default. pick selects fields, max_items caps lists, item_offset skips items. Lists over 60 KB say so.

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": "sb_api_call"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoOperation id from sb_api_find, e.g. "get:/api/sites/{siteID}/menus"
bodyNo
fileNoLocal file: multipart upload (field "file"); on a GET, saves the answer there
pathNoBare platform path, e.g. "/api/sites/{siteId}/published"; {siteId} defaults to SB_SITE
pickNoFields per list item or in a {"product":{…}} answer; dotted: "variants.id"
mergeNoPUT: deep-merge body over the current record (arrays replace)
queryNo
methodNoWith path, when id is absent: GET|HEAD|POST|PUT|PATCH|DELETE
dry_runNoDefaults to true. Pass false to actually send.
site_idNo
if_matchNoIf-Match version; shipping-config reads it itself
max_itemsNo
item_offsetNoOffset within this response, after API paging. Reads only.
path_paramsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.98.3
    • addedInput schema / properties / pick / description
      Added value: +"Fields per list item or in a {\"product\":{…}} answer; dotted: \"variants.id\""
  2. Changed4 schema fields changedv0.89.0
    • addedInput schema / properties / file
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Local file: multipart upload (field \"file\"); on a GET, saves the answer there",
      +  "properties": {
      +    "field": {
      +      "type": "string"
      +    },
      +    "path": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "path"
      +  ],
      +  "type": "object"
      +}
    • addedInput schema / properties / if_match
      Added value: +{
      +  "description": "If-Match version; shipping-config reads it itself",
      +  "type": [
      +    "string",
      +    "number"
      +  ]
      +}
    • addedInput schema / properties / merge
      Added value: +{
      +  "description": "PUT: deep-merge body over the current record (arrays replace)",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / site_id
      Added value: +{
      +  "type": "string"
      +}
  3. Changed4 schema fields changedv0.63.0
    • addedInput schema / properties / item_offset
      Added value: +{
      +  "description": "Offset within this response, after API paging. Reads only.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / method
      Added value: +{
      +  "description": "With path, when id is absent: GET|HEAD|POST|PUT|PATCH|DELETE",
      +  "type": "string"
      +}
    • addedInput schema / properties / path
      Added value: +{
      +  "description": "Bare platform path, e.g. \"/api/sites/{siteId}/published\"; {siteId} defaults to SB_SITE",
      +  "type": "string"
      +}
    • removedInput schema / required
      Removed value: -[
      -  "id"
      -]
  4. First observedv0.1.4

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds two things annotations cannot: requests are dry-run unless dry_run=false is passed, and oversized list responses self-report at 60 KB. It does not describe what a dry run actually returns, nor auth/permission expectations for an open-world mutation tool.

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?

Three tight clauses: the two invocation modes and the dry-run default are front-loaded, then the shaping parameters, then the truncation warning. No filler; every clause carries an operational fact.

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 14-parameter open-world, destructive HTTP proxy with no output schema, the description covers the critical decisions (id vs method+path, dry run, field shaping, list capping, truncation). It stops short of describing dry-run output shape or error behavior, which an agent would want before committing to a real send.

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 only 64%, and the description compensates for the weakest entries: pick (field selection, dotted paths), max_items (caps lists), item_offset (skips items within the response after API paging). Several parameters (query, body, path_params, site_id, merge semantics) remain undocumented in both places, so it adds real value but does not close the gap.

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 ('Call an operation... or a route') and immediately distinguishes the two invocation modes: by catalog id from sb_api_find, or by raw method+path for routes the catalog lacks. An agent can tell this apart from sb_api_find, which only looks operations up, without opening either schema.

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 a clear routing rule: prefer an id from sb_api_find, fall back to method+path only when the catalog lacks the route. Also signals the default-safe posture ('dry run by default'), so an agent knows it must opt in to a real send. No explicit when-not-to-use or sibling alternatives (e.g. why not sb_live_join or sb_node_read) beyond the catalog fallback.

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