Explain Promo Methodology (Messaging)

messagingmcp-explain_promo_data

Explain how the promo dataset was captured and what the tool fields mean.

Documentation lookup, no data access. Call when unsure how to interpret a promo field (e.g. promo_depth units, inferred flags, active_window vs promo_active_dates) or why an expected offer type (e.g. free shipping) has few or unreliable results.

Parameters

Name	Type	Required	Constraints	Description
topic	string	no	—	Which section of the data guide to return. 'overview' = capture model + what counts as a promotion (and what is excluded); 'fields' = per-field dictionary with derivations; 'identity' = what promo_id means (grouping vs persistence); 'dates' = date fields, active_window vs promo_active_dates, coverage; 'inferred' = observed vs forward-projected rows and provenance flags; 'quality' = caveats. Omit for overview.

Returns

• On success: {"result": {"topic": str, "content": markdown str,
• "topics": all topic names}}.
• On failure: {"error": {code, message}}
• code is not_entitled (authorization refused) or
• upstream_unavailable — both from resolving the caller's config,
• since the guide is served from a file and this tool reaches no data
• source at all.

Try it

Loading interactive widget…

Code examples

curl

curl -s https://mcp.edited.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "x-api-key: $MCP_API_KEY" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "messagingmcp-explain_promo_data",
    "arguments": {
      "topic": "example"
    }
  }
}'

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "demo", version: "1.0.0" }, { capabilities: {} });
await client.connect(
  new StreamableHTTPClientTransport(new URL("https://mcp.edited.com/mcp"), {
    requestInit: { headers: { "x-api-key": process.env.MCP_API_KEY ?? "" } },
  }),
);

const result = await client.callTool({
  name: "messagingmcp-explain_promo_data",
  arguments: {
    "topic": "example"
  },
});

Python

import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

headers = {"x-api-key": os.environ["MCP_API_KEY"]}
async with streamablehttp_client("https://mcp.edited.com/mcp", headers=headers) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool(
            "messagingmcp-explain_promo_data",
            {"topic": "example"},
        )

Input schema

{
  "type": "object",
  "properties": {
    "topic": {
      "description": "Which section of the data guide to return. 'overview' = capture model + what counts as a promotion (and what is excluded); 'fields' = per-field dictionary with derivations; 'identity' = what promo_id means (grouping vs persistence); 'dates' = date fields, active_window vs promo_active_dates, coverage; 'inferred' = observed vs forward-projected rows and provenance flags; 'quality' = caveats. Omit for overview.",
      "enum": [
        "overview",
        "fields",
        "identity",
        "dates",
        "inferred",
        "quality"
      ],
      "type": "string"
    }
  }
}

Output schema

Describes both branches of the envelope — result on success, error on a refusal. Validate against this rather than pattern-matching the prose above; see Concepts → Response shape.

{
  "type": "object",
  "properties": {
    "result": {
      "properties": {
        "topic": {
          "enum": [
            "overview",
            "fields",
            "identity",
            "dates",
            "inferred",
            "quality"
          ],
          "type": "string"
        },
        "content": {
          "type": "string"
        },
        "topics": {
          "items": {
            "enum": [
              "overview",
              "fields",
              "identity",
              "dates",
              "inferred",
              "quality"
            ],
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "topic",
        "content",
        "topics"
      ],
      "type": "object"
    },
    "error": {
      "type": "object",
      "description": "Present instead of `result` when the call was rejected. Branch on `code`; never string-match `message`.",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_input",
            "not_entitled",
            "upstream_unavailable",
            "internal"
          ]
        },
        "message": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "description": "Offending parameter, when the failure is attributable to one."
        },
        "details": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "oneOf": [
    {
      "required": [
        "result"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "x-fastmcp-wrap-result": true
}