Skip to main content
Glama
shopify-partners-mcp

shopify-partners-mcp

by amitray007

billing_watchlist

Read-only

Identifies shops that need billing attention now—frozen subscriptions, scheduled cancellations, deactivated stores, and unapplied credits in the last 90 days—using cached app event history.

Instructions

Shops that need attention now: frozen subscriptions, scheduled cancellations, deactivated stores, and credits not applied in the last 90 days. Facts only, no predictions. Computed from the app's full event history, which the server downloads once and caches for 15 minutes.

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

Input Schema

NameRequiredDescriptionDefault
appIdNoApp ID: the number or a gid:// ID. Optional when SHOPIFY_PARTNER_APP_IDS names exactly one app

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: it is 'facts only, no predictions' (so no inferred churn risk), and it is computed from the full event history that the server downloads once and caches for 15 minutes, which tells an agent to expect first-call latency and up-to-15-minute staleness. Return shape is not described, but the annotations carry most of the remaining burden.

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, front-loaded with the qualifying criteria, followed by two short clarifying clauses about prediction-free semantics and data freshness. Every clause is informative and none repeats the tool name or annotations.

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?

The tool is simple (one optional param, read-only, no output schema), and the description covers what qualifies, what it is derived from, and how fresh the data is. The main remaining gap is the shape of each watchlist entry (which fields identify the shop and the reason code), which an agent might want since there is no output schema.

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?

There is a single optional parameter, appId, and schema coverage is 100% with a description that already explains the numeric-or-gid:// format and the SHOPIFY_PARTNER_APP_IDS fallback. The prose adds nothing about appId, so the 3 baseline applies; the schema does all the work here.

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 description names the resource (a watchlist of shops) and enumerates the four concrete criteria that qualify a shop: frozen subscriptions, scheduled cancellations, deactivated stores, and unapplied credits in the last 90 days. That is far more specific than the name alone. It does not explicitly differentiate itself from siblings like churn_report or retention_cohorts, which is the only thing keeping it from a 5.

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?

'Shops that need attention now' implies a triage/action use case, but there is no explicit when-to-use guidance, no stated exclusions, and no pointer to the related tools (churn_report, mrr_movement) that overlap in subject matter. An agent must infer the routing decision from the criteria list.

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