GrowSurf

Record Sale

growsurf_record_sale

Idempotent

Record a sale/transaction for an affiliate program. Use webhooks to know when commissions are added. Requires at least one transaction identifier (externalId, transactionId, orderId, paymentId, invoiceId, paymentIntentId, or chargeId) so repeated calls are de-duplicated instead of double-paying the referrer; reuse the same one when refunding. Targets campaignId if you pass it, otherwise GROWSURF_CAMPAIGN_ID.

Input Schema

Name	Required	Description
`paidAt`	No
`orderId`	No
`chargeId`	No
`currency`	Yes
`testMode`	No	Required with `paymentProvider`: `true` for test or `false` for live. Otherwise omit.
`invoiceId`	No
`netAmount`	No
`paymentId`	No
`taxAmount`	No
`amountPaid`	No
`campaignId`	Yes	Target program id for this call: the `id` returned by `growsurf_list_campaigns`, not the program name or a share URL. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server.
`customerId`	No
`externalId`	No
`totalTaxes`	No
`description`	No
`grossAmount`	Yes
`invoiceTotal`	No
`amountCashNet`	No
`participantId`	No
`transactionId`	No
`subscriptionId`	No
`totalTaxAmount`	No
`paymentIntentId`	No
`paymentProvider`	No	Connected provider for this payment. Requires `transactionId` and `testMode`. Supply matching `grossAmount` and `currency`; other payment IDs and tax or net-amount overrides are not accepted. GrowSurf reads payment details from the provider and detects duplicate webhook/API/manual submissions.
`totalTaxAmounts`	No
`participantEmail`	No
`invoiceTotalExcludingTax`	No
`invoiceSubtotalExcludingTax`	No

Output Schema

Name	Required	Description
`message`	No	Human-readable result message.
`success`	No	`true` when the sale was recorded; `false` when it matched an existing transaction.
`duplicate`	No	`true` when the sale matched an existing transaction.
`firstSale`	No	Whether this was the referred customer's first recorded sale.
`duplicateFields`	No	Identifier fields that matched an existing transaction.
`commissionsCreated`	No	Commissions created by this duplicate request.
`matchingCommissionIds`	No	Commission ids that matched the submitted identifiers.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 13, 2026

changedInput schema / properties / campaignId / description

Previous value: -"Target program (campaign) id for this call. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server."New value: +"Target program id for this call: the `id` returned by `growsurf_list_campaigns`, not the program name or a share URL. Defaults to GROWSURF_CAMPAIGN_ID when omitted. Program IDs also identify newly created programs without restarting the server."

Changed9 schema fields changedNov 3, 2026
- addedInput schema / properties / chargeId / maxLength
```
Added value: +500
```
- addedInput schema / properties / customerId / maxLength
```
Added value: +500
```
- addedInput schema / properties / externalId / maxLength
```
Added value: +500
```
- addedInput schema / properties / invoiceId / maxLength
```
Added value: +500
```
- addedInput schema / properties / orderId / maxLength
```
Added value: +500
```
- addedInput schema / properties / paymentId / maxLength
```
Added value: +500
```
- addedInput schema / properties / paymentIntentId / maxLength
```
Added value: +500
```
- addedInput schema / properties / subscriptionId / maxLength
```
Added value: +500
```
- addedInput schema / properties / transactionId / maxLength
```
Added value: +500
```
First observedOct 8, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description goes beyond the hint by explaining the mechanism: de-duplication keys on one of seven transaction identifiers and prevents double-paying the referrer. It also discloses the targeting fallback to the GROWSURF_CAMPAIGN_ID environment variable when campaignId is omitted. It does not discuss failure modes or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, front-loaded with the purpose and followed by the dedup constraint and targeting rule. Nothing is filler, though the webhook sentence is advisory rather than operational.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 28-parameter mutation with an output schema, the description covers the two highest-risk behaviors (duplicate payouts and campaign targeting) well. It leaves out participant identification and amount/currency semantics, which are exactly the gaps a low-coverage schema cannot fill on its own.

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 only 11% across 28 parameters, so the description carries most of the burden. It usefully explains the identifier anyOf (seven accepted IDs), the refund-reuse rule, and the campaignId/default behavior, but it never mentions the participantId/participantEmail requirement, the units and meaning of the many amount fields, or currency formatting.

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?

"Record a sale/transaction for an affiliate program" gives a specific verb (record) and resource (sale/transaction) with the domain scoped to affiliate programs. It is unmistakable what the tool does, but it never contrasts itself with any sibling (e.g., participant or campaign tools), so it lands just below the top tier.

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?

It supplies two concrete usage rules: supply at least one transaction identifier so repeat calls de-duplicate, and reuse that same identifier when refunding. It also says to use webhooks to learn when commissions are added. There is no explicit when-not-to-use or named alternative, which keeps it out of the 5 tier.

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

All GrowSurf tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.