Skip to main content
Glama
Sign In

POAScan

by io.github.jakegallen
OverviewDiscussionsAdmin

Swap offer

get_swap_offer
Read-onlyIdempotent

One swap offer by offer_id with its fill and cancel events. Use it after list_swap_offers to inspect a single offer. money_moved: true when filled, null when a fill was submitted but is not final (POAScan can't see external-chain payments; the buyer may have paid, so never read null as no payment), false only when no fill tx exists. taker_credit (poa minus fee_poa) on a final fill, refund_txid on a cancel, receipt_state signed when a finalized fill carries the seller's receipt; null when not applicable. An expired offer has refund_txid null until the maker cancels; pre-fill receipts are not public.

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": {
      "offer_id": "<offer_id>"
    },
    "name": "get_swap_offer"
  }
}

Input Schema

NameRequiredDescriptionDefault
offer_idYesthe offer_id from list_swap_offers (64-hex)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / offer_id / description
      Added value: +"the offer_id from list_swap_offers (64-hex)"
  2. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them by warning that money_moved=null must never be read as 'no payment' due to POAScan's blind spot on external-chain payments. It also explains the expired-offer refund_txid timing and that pre-fill receipts are not public — the kind of caveat an agent cannot infer from any structured field.

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?

Purpose and usage are front-loaded, then the field semantics follow in a dense but relevant block. The middle sentence is a long run-on stacking several field meanings, which slightly hurts scanability, but no sentence is filler.

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?

With no output schema, the description carries the burden of return-value meaning and does explain the tricky fields (money_moved, taker_credit, refund_txid, receipt_state) plus the fill/cancel event structure. It does not enumerate all returned fields, but the ambiguous ones that would cause misreads are covered.

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?

Only one parameter, and the schema already documents it at 100% coverage ('the offer_id from list_swap_offers (64-hex)'). The description refers to offer_id but adds no format, sourcing, or validation detail beyond what the schema states, so the baseline 3 applies.

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?

Opens with a specific verb+resource+scope: 'One swap offer by offer_id with its fill and cancel events.' It explicitly separates itself from the sibling list_swap_offers by naming it as the feeding call, so an agent can distinguish single-offer inspection from listing without opening the schema.

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?

"Use it after list_swap_offers to inspect a single offer" gives a concrete triggering condition and names the alternative. It does not state exclusions (e.g., use get_swap_status instead when you want lifecycle state), so it stops short of a full when/when-not map.

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

All POAScan 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