Skip to main content
Glama
benswel

QR for Agent

by benswel
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

record_conversion

Track QR code ROI by recording post-scan conversions like purchases or signups with optional monetary values for performance analysis.

Instructions

Record a post-scan conversion event (purchase, signup, etc.) for a QR code you own. Use this to track ROI — e.g., when a user scans a QR code and then makes a purchase, record a 'purchase' conversion with the order value. For client-side tracking without code, use the tracking pixel: .

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
short_idYesThe short_id of the QR code this conversion is for.
eventYesThe conversion event name (e.g., "purchase", "signup", "add_to_cart"). Use consistent names to aggregate stats.
valueNoOptional monetary value of the conversion (e.g., 49.99).
metadataNoOptional JSON metadata (e.g., product ID, order number).

Implementation Reference

  • packages/mcp/src/tools.ts:844-867 (handler)
    The record_conversion MCP tool definition, which uses the apiRequest helper to POST data to the /api/conversions endpoint.
    record_conversion: {
  description:
    "Record a post-scan conversion event (purchase, signup, etc.) for a QR code you own. Use this to track ROI — e.g., when a user scans a QR code and then makes a purchase, record a 'purchase' conversion with the order value. For client-side tracking without code, use the tracking pixel: <img src=\"https://yourhost/t/{short_id}?event=purchase&value=49.99\">.",
  inputSchema: z.object({
    short_id: z.string().describe("The short_id of the QR code this conversion is for."),
    event: z
      .string()
      .max(100)
      .describe(
        'The conversion event name (e.g., "purchase", "signup", "add_to_cart"). Use consistent names to aggregate stats.'
      ),
    value: z
      .number()
      .optional()
      .describe("Optional monetary value of the conversion (e.g., 49.99)."),
    metadata: z
      .record(z.string(), z.unknown())
      .optional()
      .describe("Optional JSON metadata (e.g., product ID, order number)."),
  }),
  handler: async (input: Record<string, unknown>) => {
    return apiRequest("/api/conversions", { method: "POST", body: input });
  },
},

Tool Definition Quality

A4.4/5.0
Behavior3/5

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

No annotations provided, so description carries full burden. Mentions ownership requirement ('QR code you own') implying authorization constraints, and explains business context (ROI tracking). However, lacks disclosure on idempotency, rate limits, or return value format for this write operation.

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?

Three sentences with zero waste: first defines action, second provides ROI context with example, third gives alternative method. Front-loaded with core purpose. No redundant or filler text.

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?

Comprehensive for a conversion tracking endpoint with 100% schema coverage. No output schema exists, and while description doesn't detail return values, this is acceptable for a simple logging endpoint where success/failure is implicit. Mention of ownership covers auth context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, establishing baseline 3. Description adds value by mapping abstract parameters to concrete examples in narrative (e.g., 'purchase', '49.99') and demonstrating usage via the tracking pixel URL example, reinforcing the semantic meaning of short_id, event, and value.

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?

Description uses specific verb 'Record' with clear resource 'post-scan conversion event' and context 'for a QR code you own'. Distinguishes clearly from sibling get_conversions by specifying this is for writing events (purchase, signup) rather than retrieving them.

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?

Provides explicit when-to-use guidance ('Use this to track ROI') with concrete scenario (scan → purchase). Critically, it distinguishes this server-side API from the alternative client-side tracking pixel ('For client-side tracking without code, use...'), preventing incorrect tool selection.

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

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/benswel/qr-agent-core'

If you have feedback or need assistance with the MCP directory API, please join our Discord server