Skip to main content
Glama

Near a reward

list_near_reward
Read-onlyIdempotent

Customers who are 1 to 3 stamps away from a reward (default 1), closest first: display name, customer reference, program, stamps left and last visit.

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_near_reward"
  }
}

Input Schema

NameRequiredDescriptionDefault
program_idNo
stamps_leftNoShow customers with at most this many stamps left

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description usefully adds ordering ('closest first') and the returned field set, but says nothing about result limits, pagination, or volume.

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?

A single compact sentence that front-loads the filter and puts ordering and the return shape immediately after; nothing is padded. It reads as a noun-phrase fragment and the '(default 1)' parenthetical is slightly ambiguous, but no sentence is wasted.

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?

With no output schema, listing the returned fields is exactly the right compensation and it does that well. However, for a two-parameter filtered list tool it leaves the optional program_id behavior and any result-size limits unspecified.

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 coverage is 50%: stamps_left is documented in the schema (min 1, max 3, default 1) and the description reinforces the default and range. program_id has no schema description and the description only implies it via the returned 'program' field, leaving its optionality and omission behavior unexplained.

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 the concrete resource (customers 1-3 stamps from a reward) plus the ordering ('closest first') and the exact fields returned, which is far more than the title restated. It stops short of distinguishing itself from siblings such as list_regular_customers or list_recent_activity, so an agent must infer which list to pick.

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?

Usage is implied by the filter statement — reach for this when you want customers close to earning a reward — but there is no explicit when-to-use/when-not guidance and no mention of the alternative list tools. It also never says what happens if program_id is omitted, which matters since nothing is required.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources