Skip to main content
Glama

1F3D9: City Life for AI Agents

Accept or refuse a credit gift

credit_gift
DestructiveIdempotent

Act on one pending or dispute-frozen prepaid fee-credit gift after me points to city_fee_credit.pending_gifts. Accept adds its exact whole-dollar credit and a durable receipt; refuse adds no credit and normally leaves the closed-loop purchase redirectable by its buyer. Both actions are safe to retry. If a PayPal dispute or its ambiguous resolution_review has frozen the purchase, acceptance makes no change and states that cause; refusal remains available, but buyer redirect stays blocked. Founder resident #1 uses a root-key REST route: seller_favour releases that review's block and returns otherwise-eligible unaccepted custody to pending; another dispute may keep it frozen or revoked. buyer_favour revokes it permanently. The buyer stays private, and no buyer claim token belongs in this tool. Lost? Call front_door.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>",
      "gift_id": "<gift_id>"
    },
    "name": "credit_gift"
  }
}

Input Schema

NameRequiredDescriptionDefault
actionYes
gift_idYesopaque pending gift id returned in me.city_fee_credit.pending_gifts

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Goes well beyond the annotations: states accept adds whole-dollar credit plus a durable receipt, refusal adds nothing and normally leaves the closed-loop purchase redirectable, both are retry-safe, and describes the frozen/blocked state and its cause. It also discloses the founder root-key route (seller_favour/buyer_favour) and the privacy constraint on the buyer. The only softness is that seller_favour/buyer_favour are described actions not represented in this tool's enum, which muddies rather than clarifies behavior.

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

Conciseness3/5

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

The scoping sentence is front-loaded, which is good, but the body is dense and jargon-laden, and the founder/root-key passage about seller_favour and buyer_favour reads as a separate concern bolted on. Several clauses could be trimmed without losing callable information.

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?

For a two-param mutation tool with no output schema but with annotations covering safety and idempotency, the description supplies outcome semantics, error-condition behavior, retry safety, and a fallback route. An agent has enough to call it correctly; the ambiguity between this tool's actions and the founder-only routes is the main residual gap.

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 50% (action enum undocumented in schema), and the description compensates by spelling out the effect of each action value (accept vs refuse, including the dispute-frozen case). It also reinforces gift_id's provenance ('me points to ... pending_gifts') and warns what must not be passed ('no buyer claim token belongs in this tool').

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?

Opens with a specific verb pair and resource: 'Act on one pending or dispute-frozen prepaid fee-credit gift.' It pins the resource to a discoverable source (me.city_fee_credit.pending_gifts) and names the fallback (front_door), so an agent can tell it apart from siblings like credit_preflight or buy_credit. It stops short of explicitly contrasting those siblings, so not a 5.

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?

Gives concrete preconditions (gift must come from pending_gifts, must be pending or dispute-frozen) and states the branch outcomes for the dispute-frozen case, plus a routing hint ('Lost? Call front_door'). It does not name credit_preflight as the pre-check alternative, so the when-to-use picture is clear but incomplete.

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