Skip to main content
Glama

openaffiliate-mcp

by io.github.sonpiaz
OverviewDiscussionsAdmin

Search Programs

search_programs
Read-onlyIdempotent

Use to discover active affiliate programs by keyword, category, commission type, or verified status. Returns matching summaries with canonical slugs, commission figures, signup links, and citable markdownUrl fields. Do not use to check a known brand's paused or no-program status; call get_program with its slug. Call list_categories for category names, then get_program for recommendation guidance and restrictions before recommending a match.

Input Schema

NameRequiredDescriptionDefault
queryNoSearch keyword to match against name, description, tags, or category
categoryNoFilter by exact category name as returned by list_categories (case-sensitive, not a slug), e.g. 'AI', 'Email Marketing'
verified_onlyNoWhen true, return only programs whose terms were checked on the brand's own program page. False or omitted includes unverified programs with unconfirmed terms
commission_typeNoFilter by payment structure: recurring = paid on each renewal within the commission duration; one-time = paid once per qualifying referral; tiered = commission varies by performance level. Omit to include all types, including hybrid

Output Schema

NameRequiredDescriptionDefault
programsYesMatching active programs; empty when no listings match

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / category / description
      Previous value: -"Filter by category name (e.g. 'AI & ML Tools', 'Email Marketing')"New value: +"Filter by exact category name as returned by list_categories (case-sensitive, not a slug), e.g. 'AI', 'Email Marketing'"
    • changedInput schema / properties / commission_type / description
      Previous value: -"Filter by commission type"New value: +"Filter by payment structure: recurring = paid on each renewal within the commission duration; one-time = paid once per qualifying referral; tiered = commission varies by performance level. Omit to include all types, including hybrid"
    • changedInput schema / properties / verified_only / description
      Previous value: -"When true, return only verified programs"New value: +"When true, return only programs whose terms were checked on the brand's own program page. False or omitted includes unverified programs with unconfirmed terms"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "programs": {
+      "description": "Matching active programs; empty when no listings match",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "category": {
+            "description": "Exact registry category name, as returned by list_categories",
+            "type": "string"
+          },
+          "commission": {
+            "additionalProperties": false,
+            "description": "Commission structure and figures; unverified terms are unconfirmed, not guaranteed earnings",
+            "properties": {
+              "currency": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Currency code for monetary amounts; null when unspecified"
+              },
+              "mode": {
+                "description": "Figure format: percentage uses percent units, flat uses currency units, tiered and hybrid require rate/conditions to interpret; unknown means no published figure",
+                "enum": [
+                  "percentage",
+                  "flat",
+                  "tiered",
+                  "hybrid",
+                  "unknown"
+                ],
+                "type": "string"
+              },
+              "rate": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  }
+                ],
+                "description": "Raw source wording; prefer mode and value"
+              },
+              "type": {
+                "description": "Payment structure: recurring pays on renewals within the commission duration; one-time pays once per qualifying referral; tiered varies by performance level; hybrid combines payment structures",
+                "enum": [
+                  "recurring",
+                  "one-time",
+                  "tiered",
+                  "hybrid"
+                ],
+                "type": "string"
+              },
+              "value": {
+                "anyOf": [
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Commission in percent units for percentage mode (30 means 30%), or currency units for flat mode; null when no single numeric figure is available"
+              }
+            },
+            "required": [
+              "type",
+              "mode",
+              "value",
+              "rate",
+              "currency"
+            ],
+            "type": "object"
+          },
+          "cookieDays": {
+            "description": "Attribution window in days; omitted until terms are verified",
+            "type": "number"
+          },
+          "markdownUrl": {
+            "description": "Citable program page in Markdown on openaffiliate.dev",
+            "type": "string"
+          },
+          "name": {
+            "description": "Display name of the program or brand",
+            "type": "string"
+          },
+          "shortDescription": {
+            "description": "Brief product summary; unverified cookie, payout and approval claims are withheld",
+            "type": "string"
+          },
+          "signupUrl": {
+            "description": "Affiliate signup or program URL; falls back to the brand website when no signup URL is stored",
+            "type": "string"
+          },
+          "slug": {
+            "description": "Canonical slug to pass to get_program",
+            "type": "string"
+          },
+          "verified": {
+            "description": "True when the terms have been checked on the brand's own program page; false means unconfirmed",
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "slug",
+          "name",
+          "category",
+          "shortDescription",
+          "commission",
+          "verified",
+          "signupUrl",
+          "markdownUrl"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "programs"
+  ],
+  "type": "object"
+}
  2. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds value beyond that: it describes what results look like (canonical slugs, commission figures, signup links, citable markdownUrl) and scopes the search to active programs only. It does not discuss pagination or result limits, so it stops just short of a 5.

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?

Front-loaded with the primary use case, then routing constraints in descending order of importance. The final sentence bundles two instructions (list_categories, then get_program) which is slightly dense, but every clause carries actionable routing information.

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

Completeness5/5

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

An output schema exists, yet the description still summarizes the return fields so the agent knows slugs and markdownUrl are available for citation. For a zero-required-param search tool with full schema coverage and a clear sibling map, nothing an agent needs to call it correctly 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 all four parameters are already documented with the enum and case-sensitivity rules. The description restates the filter dimensions (keyword, category, commission type, verified status) but adds no syntax or format guidance beyond the schema, which is the expected baseline here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (discover affiliate programs) with the searchable dimensions (keyword, category, commission type, verified status) and the returned shape. It also explicitly differentiates itself from get_program and list_categories, so the agent can pick between siblings without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names positive conditions (discovery by keyword/category/commission/verified), an explicit exclusion (do not use to check a known brand's paused status — use get_program with its slug), and a prerequisite workflow (list_categories for category names, get_program for recommendation guidance before recommending).

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

All openaffiliate-mcp toolsInspect
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.

Resources