Skip to main content
Glama

ForthClear Liquidation Marketplace

Open a dispute

open_dispute
DestructiveIdempotent

Report a problem with an order. not_received is allowed while the order is marked shipped. Other reasons require a delivered order waiting for confirmation. This records the issue, pauses the seller payout, and notifies ForthClear. Requires sign-in with buyer access. OAuth discovery: /.well-known/oauth-authorization-server (scope buyer:write). Sensitive: requires user approval each time.

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": {
      "order_id": "<order_id>",
      "reason": "<reason>",
      "description": "<description>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "open_dispute"
  }
}

Input Schema

NameRequiredDescriptionDefault
reasonYesDispute reason. not_received is allowed while the order is shipped. The other reasons require delivered_pending_confirmation.
order_idYesForthClear order id
photo_urlsNoOptional evidence URLs
descriptionYesFree-text description of the issue
idempotency_keyYesRequired. 8–200 characters (letters, digits, . _ : -). The same key returns the original result for 24 hours and is sent to Stripe as Idempotency-Key.
requested_actionNoResolution the buyer is requesting

Output Schema

NameRequiredDescriptionDefault
slaYes
statusYes
messageYes
successYes
order_idYes
opened_atYes
dispute_idYes
next_actionsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedInput schema / properties / idempotency_key
      Added value: +{
      +  "description": "Required. 8–200 characters (letters, digits, . _ : -). The same key returns the original result for 24 hours and is sent to Stripe as Idempotency-Key.",
      +  "type": "string"
      +}
    • changedInput schema / properties / reason / description
      Previous value: -"Dispute reason"New value: +"Dispute reason. not_received is allowed while the order is shipped. The other reasons require delivered_pending_confirmation."
    • changedInput schema / properties / reason / enum
      Previous value: -[
      -  "missing_units",
      -  "quality_issue",
      -  "damaged",
      -  "wrong_item",
      -  "other"
      -]New value: +[
      +  "missing_units",
      +  "quality_issue",
      +  "damaged",
      +  "wrong_item",
      +  "not_received",
      +  "other"
      +]
    • changedInput schema / required
      Previous value: -[
      -  "order_id",
      -  "reason",
      -  "description"
      -]New value: +[
      +  "order_id",
      +  "reason",
      +  "description",
      +  "idempotency_key"
      +]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "dispute_id": {
      +      "type": "string"
      +    },
      +    "message": {
      +      "type": "string"
      +    },
      +    "next_actions": {
      +      "items": {
      +        "properties": {
      +          "description": {
      +            "type": "string"
      +          },
      +          "type": {
      +            "type": "string"
      +          }
      +        },
      +        "required": [
      +          "type",
      +          "description"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "opened_at": {
      +      "type": "string"
      +    },
      +    "order_id": {
      +      "type": "integer"
      +    },
      +    "sla": {
      +      "properties": {
      +        "admin_review_deadline": {
      +          "type": "string"
      +        },
      +        "admin_review_within_hours": {
      +          "type": "integer"
      +        }
      +      },
      +      "required": [
      +        "admin_review_within_hours",
      +        "admin_review_deadline"
      +      ],
      +      "type": "object"
      +    },
      +    "status": {
      +      "type": "string"
      +    },
      +    "success": {
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "success",
      +    "message",
      +    "dispute_id",
      +    "order_id",
      +    "status",
      +    "opened_at",
      +    "sla",
      +    "next_actions"
      +  ],
      +  "type": "object"
      +}
  2. Added

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds the operational consequences an agent could not infer: the seller payout is paused, ForthClear is notified, and the issue is recorded. It also discloses the auth requirement (buyer sign-in, buyer:write scope, OAuth discovery endpoint) and that the call is sensitive and needs per-call user approval.

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?

Five tight sentences, front-loaded with the action and followed by eligibility, side effects, and auth. No filler, though the auth/discovery sentence is dense and could be split or trimmed for faster scanning.

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?

For a destructive, idempotent mutation with an output schema, the description covers everything an agent needs before calling: eligibility by reason, side effects on payouts and notifications, and the auth/approval requirements. Return values are handled by the output schema, so nothing material 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 six parameters including the reason enum, idempotency key rules, and photo_urls limits are already documented in the schema. The description only restates the reason-eligibility rule, adding little parameter meaning beyond what the structured fields provide.

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?

The description opens with a specific verb and resource: 'Report a problem with an order,' which maps cleanly to the tool name open_dispute. It does not explicitly name get_dispute_status as the tracking counterpart, but the purpose is unambiguous and distinguishable from order-lifecycle siblings like cancel_order or confirm_order.

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 states concrete eligibility conditions: 'not_received is allowed while the order is marked shipped' and other reasons require a delivered order awaiting confirmation. That is real when-you-can-use guidance beyond the schema. It stops short of naming an alternative (e.g., get_dispute_status for follow-up) or saying when not to open a dispute.

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