Skip to main content
Glama
shopify-partners-mcp

shopify-partners-mcp

by amitray007

list_events

Read-only

Retrieve a filtered historical timeline of app installs, uninstalls, subscription changes, charges, earnings, and credits for Shopify Partner analytics.

Instructions

List the historical event timeline: installs, uninstalls, subscription changes, charges, earnings, and credits. Needs the Manage apps permission.

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

Input Schema

NameRequiredDescriptionDefault
afterNonextCursor from the previous page
appIdNoApp ID: the number or a gid:// ID
firstNoPage size, default 100
shopIdNoShop ID: the number or a gid:// ID
eventTypesNoEventType values, e.g. RELATIONSHIP_UNINSTALLED
occurredAtMaxNoEnd of the window. Defaults to now; the window is at most 365 days
occurredAtMinNoStart of the window. Defaults to 30 days before the end

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.6/5.0
Behavior3/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 structurally. The description adds genuinely new behavioral context in the form of the required 'Manage apps' permission, but it does not mention ordering, the maximum 365-day window, or pagination behavior — all of which live only in the schema.

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 short sentences, zero filler. The resource and its contents are front-loaded, and the permission requirement follows as a compact operational note.

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 read-only, filter-driven list tool with full schema coverage and readOnly/openWorld annotations, the description covers what the tool returns and what access it needs. Remaining gaps (sort order, explicit pagination hint) are minor and largely mitigated by the schema and the absence of an 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?

Schema description coverage is 100% across all 7 parameters, so defaults, cursors, date formats, and the 365-day window are already documented. The description's list of event categories loosely maps to the eventTypes parameter but adds no filtering syntax or format 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?

Names a specific verb and resource ('List the historical event timeline') and enumerates the concrete event categories it returns (installs, uninstalls, subscription changes, charges, earnings, credits), so an agent knows the content immediately. It does not distinguish itself from overlapping siblings such as list_transactions or shop_history, so it stops short of 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?

The description supplies a real usage prerequisite — 'Needs the Manage apps permission' — which tells an agent that calls may fail without that scope. However, it offers no when-to-use vs. when-to-prefer-another-tool guidance and no exclusions, so the selection guidance is only implied by the enumerated event types.

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