Skip to main content
Glama
shopify-partners-mcp

shopify-partners-mcp

by amitray007

trial_funnel

Read-only

Measure Shopify app conversion for installs in a date range: count subscriptions, trial starts, paid and current paying shops, plus conversion rates and median days to first payment.

Instructions

For shops that first installed in the range: how many subscribed, started a trial, paid, and pay now, with conversion rates and median days from install to first payment. 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": "trial_funnel"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoEnd. Defaults to now: YYYY-MM-DD (UTC) or an ISO 8601 date-time
fromNoStart. Defaults to 90 days ago: YYYY-MM-DD (UTC) or an ISO 8601 date-time
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 establish readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real operational context beyond them: the computation scans the app's full event history, the server downloads it once and caches it for 15 minutes — meaning a first call is expensive and results can be up to 15 minutes stale. It does not discuss cost limits or failure modes, but the caching note is genuinely useful.

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 cohort scope and the metrics produced, then the caching caveat. Nothing is redundant and no wording is padding.

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?

With no output schema, the description does the work of enumerating the returned metrics (counts per stage, conversion rates, median days to first payment), which is what an agent needs to decide relevance. It is nearly complete for a three-parameter read-only report; only tie-breaking guidance against similar analytics siblings is missing.

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 from, to, and appId are already fully documented, setting the baseline at 3. The description adds cohort meaning to from/to — they bound install date, not payment date — which is a modest semantic gain but no format or default detail beyond the schema.

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 a concrete verb-and-resource: it counts shops that first installed in the range and reports subscribed / trial / paid / pay-now stages with conversion rates and median days to first payment. The 'first installed in the range' cohort framing separates it from a general revenue or retention report, though it never names a specific sibling to contrast with.

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?

Usage is implied by the cohort definition ('for shops that first installed in the range'), which tells an agent this is a post-install conversion funnel rather than a period-over-period revenue view. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative such as install_summary or retention_cohorts.

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