fomox402
Server Details
Broker + MCP server for last-bidder-wins on-chain games on Solana via x402 micropayments.
- Status
- Unhealthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- staccDOTsol/staccbot-tg
- GitHub Stars
- 0
- Server Listing
- fomox402 — Last-Bidder-Wins on Solana
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.8/5 across 25 of 25 tools scored.
Each tool targets a distinct resource or action: agent config, operators, game rounds, webhooks, tower floors, firm events, and agent lifecycle. There is no ambiguity between tools like claim_dividend and claim_winnings, which are clearly separated by the concept of dividends vs. winner payout.
All tool names follow a consistent snake_case verb_noun pattern, e.g., agent_equip_get, place_bid, register_webhook. No mixing of camelCase or other conventions, making the naming predictable.
25 tools cover a complex domain involving agent management, game rounds, tower floors, webhooks, and firm events. While a bit heavy, each tool earns its place and the count is appropriate for the scope.
The tool surface covers the full lifecycle: agent registration, game creation, bidding, claiming, dividend collection, key burning, operator management, tower floor operations, webhook subscription, and faucet topup. No obvious gaps exist.
Available Tools
25 toolsagent_equip_getAgent Equip GetARead-onlyIdempotentInspect
Read an agent's STRAT config (the parameters its tower floor runs on).
WHAT IT DOES: GETs /v1/agents/:agent_wallet/config. Public read — anyone
can audit any agent's strategy. The returned version is the CAS token
you pass to agent_equip_set as expected_version on the next write.
WHEN TO USE: before agent_equip_set (to compute the next expected_version), or just to inspect what a competitor's floor is configured to do.
RETURNS: AgentConfig — { agent_wallet, version, updated_at, updated_by, config: { strategy, max_bid_raw, cooldown_sec, aggression_bps, custom } }.
FAILURE MODES: equip_get_failed (404) — agent has never written a config; treat the version baseline as 0 on the first write.
RELATED: agent_equip_set (write), agent_operators_list (who can write).
| Name | Required | Description | Default |
|---|---|---|---|
| agent_wallet | Yes | Agent wallet pubkey (base58). Same address returned by register_agent / get_me. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds 'public read' and explains failure mode (404 with action). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (WHAT IT DOES, WHEN TO USE, RETURNS, FAILURE MODES, RELATED). Every sentence provides value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description explains return structure, failure modes, and usage context. Complete for a read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters. Description adds context on where the wallet address comes from (register_agent/get_me), slightly improving over schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool reads an agent's STRAT config, specifies the endpoint, and distinguishes from sibling tools like agent_equip_set and agent_operators_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: before agent_equip_set to get expected_version, or to inspect a competitor's config. Also mentions related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
agent_equip_setAgent Equip SetADestructiveInspect
Write a STRAT config with a caller-signed payload (CAS-protected).
WHAT IT DOES: POSTs /v1/agents/:agent_wallet/config with { payload,
signature }. Broker verifies the signature against the agent's owner key OR
any wallet on the operator whitelist (see agent_operators_list), checks
expected_version against the current AgentConfig.version, and writes the
new config atomically. Headless — the broker NEVER signs.
WHEN TO USE: after a tower floor is claimed, push the STRAT config the tower v0 worker should run. Write again whenever you want to retune the strategy. Refetch with agent_equip_get on a 409 conflict and retry with the bumped expected_version.
PAYLOAD CANONICALISATION: broker re-stringifies payload with sorted keys
and no whitespace before verifying the signature. Sign that exact form.
RETURNS: AgentConfig — same shape as agent_equip_get, with version
incremented to the new high-water mark.
FAILURE MODES: equip_set_failed (bad_signature) — payload != signed bytes equip_set_failed (signer_not_authorized) — signer is neither owner nor operator equip_set_failed (version_mismatch) — refetch + retry (broker 409) equip_set_failed (payload_expired) — broker 410 equip_set_failed (nonce_replayed) — broker rejected duplicate nonce
RELATED: agent_equip_get (read current version), agent_operators_set (grant another wallet permission to write configs on this agent's behalf).
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | Canonical config payload. Caller signs the JCS-canonicalised JSON of this object with the agent owner key OR a whitelisted operator key. | |
| signature | Yes | Base58 ed25519 signature over the canonical JSON of `payload`. Sign client-side; the broker never signs. | |
| agent_wallet | Yes | Agent wallet whose config is being updated. The broker indexes config by this wallet. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description explains the CAS protocol, signature verification, atomic writes, broker behavior (never signs), and detailed failure modes. It fully discloses behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured into sections (WHAT IT DOES, WHEN TO USE, etc.), uses clear language, and every sentence adds value. No fluff, and it is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested objects, CAS, signatures), the description covers all necessary aspects: usage context, return type, failure modes, and related tools. It is complete for an AI agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds critical semantics: it clarifies payload canonicalisation (sorted keys, no whitespace), signature format (Base58 ed25519), and the role of agent_wallet. This exceeds what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it writes a STRAT config using a caller-signed payload (CAS-protected), and it distinguishes from siblings by noting that agent_equip_get reads the config and agent_operators_set manages permissions. The purpose is clear and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: after a tower floor is claimed or when retuning the strategy. It also advises on conflict handling (409 conflict) and mentions related tools for reference. No ambiguity remains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
agent_operators_listAgent Operators ListARead-onlyIdempotentInspect
Read an agent's operator whitelist (who can write configs on its behalf).
WHAT IT DOES: GETs /v1/agents/:agent_wallet/operators. Public read.
WHEN TO USE: before agent_equip_set (confirm the signer wallet is on the list), or to audit who else has write access to a competitor's config.
RETURNS: { agent_wallet, owner, operators: [{ wallet, role: 'owner'|'operator', added_at, added_by }], count }.
RELATED: agent_operators_set (mutate — owner-only), agent_equip_set (operators may write configs but not modify this list).
| Name | Required | Description | Default |
|---|---|---|---|
| agent_wallet | Yes | Agent wallet whose operator whitelist you want to read. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false; description adds endpoint path and 'Public read' context, enhancing clarity without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with labeled sections (WHAT IT DOES, WHEN TO USE, RETURNS, RELATED); front-loaded summary sentence; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With rich annotations, output schema described in RETURNS, and single parameter, description fully covers purpose, usage, and return format. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter with 100% schema coverage; description merely restates the schema's purpose ('Agent wallet whose operator whitelist you want to read'), adding no new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Read an agent's operator whitelist' with specific verb and resource, and distinguishes from siblings like agent_operators_set (mutate) and agent_equip_set (operators may write configs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends usage before agent_equip_set or for auditing, and references alternative tools for mutation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
agent_operators_setAgent Operators SetADestructiveInspect
Mutate the operator whitelist with an owner-signed payload.
WHAT IT DOES: POSTs /v1/agents/:agent_wallet/operators with { payload, signature }. Broker enforces that the signer is the OWNER (agent_wallet itself) — operator-signed mutations of the whitelist are rejected even if the signer is otherwise authorised to write configs. Headless — the broker NEVER signs.
WHEN TO USE: granting / revoking write access for a sidecar process, rotating an operator key, or wiping the whitelist before retiring an agent.
OPS:
add — append operator to the list (idempotent on existing entry)
remove — drop operator from the list (idempotent on missing entry)
set — replace the entire list with operators (use [] to wipe)
PAYLOAD CANONICALISATION: broker re-stringifies payload with sorted keys
and no whitespace before verifying the signature. Sign that exact form.
RETURNS: OperatorsList after the mutation.
FAILURE MODES: operators_set_failed (bad_signature) — payload != signed bytes operators_set_failed (signer_not_owner) — only the owner may mutate the list operators_set_failed (payload_expired) — broker 410 operators_set_failed (nonce_replayed) — duplicate nonce
RELATED: agent_operators_list (read), agent_equip_set (the permission you're granting).
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | Canonical operator-mutation payload. MUST be signed by the OWNER key (operator signatures are rejected for whitelist edits). | |
| signature | Yes | Base58 ed25519 signature over the canonical JSON of `payload`. Sign with the OWNER key. | |
| agent_wallet | Yes | Agent wallet whose operator list is being mutated. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description explains signer enforcement (owner only), headless broker behavior, payload canonicalization, and all failure modes, providing comprehensive behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (WHAT IT DOES, WHEN TO USE, OPS, etc.) and every sentence earns its place. It is front-loaded with the main purpose and uses bullet points for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with owner signature, canonicalization, multiple failure modes), the description covers all essential aspects: usage, operations, payload format, return type, and failure reasons. Output schema is present, but the description still enriches understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds crucial meaning: explains payload structure, canonical JSON requirement, signature format (Base58 ed25519), and the semantics of each op (add/remove/set). This exceeds schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Mutate the operator whitelist with an owner-signed payload' and provides specific use cases. It distinguishes from sibling tools like agent_operators_list (read) and agent_equip_set (permission granting).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'WHEN TO USE' section explicitly lists scenarios (granting/revoking, rotating, wiping) and the 'RELATED' section points to alternative tools. The 'OPS' details clarify when to use each operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
burn_keyBurn KeyADestructiveInspect
Burn ONE key on a round to permanently boost your share on the remaining keys.
WHAT IT DOES: invokes the Anchor program's burn_key_token instruction.
The burnt key's stake is folded into the round's divPerKeyScaled,
increasing the per-key dividend rate for every remaining keyholder.
Your remaining keys benefit proportionally to your share of post-burn keys.
WHEN TO USE: only when you hold many keys (>5) on a round whose pot is still ratcheting up. The math: if your_keys / total_keys is large, burning ONE key transfers a big chunk of your-vs-other dividend power — but you keep the rest of your keys. if your_keys / total_keys is small, the burn mostly subsidises others.
IRREVERSIBLE: burnt keys are gone. The on-chain account is closed and the rent is reclaimed; you cannot re-mint a key without placing a new bid.
RETURNS: { tx (Solana sig), gameId, keysBefore, keysAfter (= keysBefore - 1), newDivPerKeyScaled (the boosted rate) }.
FAILURE MODES: burn_key_failed (no_keys) — you don't hold any keys on this round burn_key_failed (round_settled) — round is already gameOver
ADVANCED USE — counter-burn defence: if a competitor is dominating divs by holding many keys, burning your own can flip the per-key rate higher than their additional bid cost, pricing them out.
RELATED: claim_dividend (collect what your keys earned), place_bid (mints a fresh key — opposite of this).
| Name | Required | Description | Default |
|---|---|---|---|
| gameId | Yes | Round you hold keys on and want to burn one of. | |
| api_key | No | Bearer api_key (or env). Must be the wallet that holds the keys. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint=true, and the description adds irreversible behavior ('burnt keys are gone'), account closure, and failure modes, giving full insight into consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, but slightly verbose. Every section serves a purpose, though some redundancy between description and schema exists for parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: what, when, failure modes, advanced use, related tools. Despite missing output schema in provided info, the description includes return fields, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description does not add new meaning beyond the schema's parameter descriptions. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Burn ONE key on a round to permanently boost your share on the remaining keys,' specifying the exact resource and action. It distinguishes from siblings by mentioning related tools like claim_dividend and place_bid.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'WHEN TO USE' section explains the condition (hold many keys, pot still ratcheting up) and provides mathematical guidance. Also includes advanced counter-burn defense, making the decision clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
claim_dividendClaim DividendADestructiveInspect
Withdraw your accrued $fomox402 key dividends from a specific round.
WHAT IT DOES: invokes the Anchor program's distribute instruction to pay
out the dividend share owed to your keys on this round. Each key earns
(divPerKeyScaled - your_lastClaimed_divPerKeyScaled) / 1e18 × your_keys
$fomox402 — i.e., your share of every bid placed AFTER you got each key.
WHEN TO USE: any time post-bid. Dividends accrue continuously as later bids come in; you can claim mid-round or wait until settle. Most agents claim once per round, after settle, to minimize fees.
WHO CAN CALL: any agent who holds at least 1 key on the round. Reads your key count from the on-chain account, so api_key MUST match the wallet that placed the bids.
RETURNS: { tx (Solana sig), gameId, claimedRaw (string, raw atomic units), newDivPerKeyScaledClaimed (the new high-water mark) }.
FAILURE MODES: dividend_failed (no_keys) — you don't hold keys on this round dividend_failed (zero_owed) — already up-to-date, no new dividends dividend_failed (rpc) — Solana RPC, retry
DIFFERENCES FROM claim_winnings:
winnings = the round-end pot (one-time, only to head bidder)
dividends = per-key passive income (every keyholder, continuous)
RELATED: claim_winnings (round-end pot), get_game.yourClaimableDividend (check before claiming), burn_key (advanced — boost your dividend share).
| Name | Required | Description | Default |
|---|---|---|---|
| gameId | Yes | Round you hold keys on. Get from get_game where yourKeys > 0. | |
| api_key | No | Bearer api_key (or env) — MUST be the wallet that holds the keys. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the invocation of the 'distribute' instruction, dividend calculation, failure modes, return structure, and that api_key must match the wallet. Annotations confirm destructiveHint=true and readOnlyHint=false, and the description adds context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, but somewhat lengthy. However, every sentence earns its place; no unnecessary fluff. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, 100% schema coverage, and an output schema (implied by description of return), the description covers failure modes, differences from related tools, and usage guidance. Everything an agent needs to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description adds value by explaining that gameId should come from get_game where yourKeys>0 and that api_key must be the wallet holding keys. Could be more explicit about api_key being optional, but overall adds meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool withdraws accrued dividends from a specific round, explains the calculation, and distinguishes it from claim_winnings. It is a specific verb+resource with clear differentiation from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'WHEN TO USE', 'WHO CAN CALL', and 'DIFFERENCES FROM claim_winnings'. It clearly states when to use (any time post-bid) and gives a recommendation to minimize fees. Also notes prerequisites (hold at least 1 key).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
claim_winningsClaim WinningsADestructiveInspect
Settle a finished round and pay out the winner.
WHAT IT DOES: invokes the Anchor program's claim instruction, which
atomically distributes the pot per the round's split bps:
winnerBps → last bidder (the winner)
creatorBps → round creator
refsBps → winner's referrer (if set)
devBps → staccpad.fun dev wallet
Marks the round gameOver=true so list_games filters it out.
WHEN TO USE: after a round's deadline has passed (deadline ≤ now) and the
round is not yet gameOver. The broker also runs an autoclaim worker that
calls this on your behalf within ~30s of expiry, so manual claims are an
optimization, not a requirement.
PERMISSIONLESS: anyone can call claim_winnings on any expired round — the on-chain program routes the funds correctly regardless of who pays the tx fee. So if you're the winner and the auto-claim worker is slow, just call this yourself.
RETURNS: { tx (Solana sig), gameId, payouts: { winner: { address, amountRaw }, creator: {...}, ref?: {...}, dev: {...} } }.
FAILURE MODES: claim_failed (not_expired) — deadline hasn't passed yet claim_failed (already_claimed) — round was already settled (gameOver) claim_failed (rpc) — Solana RPC issue, retry in a few seconds
RELATED: claim_dividend (the per-key share — separate from this winner payout), get_game (verify deadline), play (auto-handles winner check).
| Name | Required | Description | Default |
|---|---|---|---|
| gameId | Yes | Round to settle. Must be expired (deadline ≤ now) and not yet gameOver. | |
| api_key | No | Bearer api_key (or env). Pays the Solana network fee but does NOT need to be the winner — anyone can settle on the winner's behalf. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses destructive nature (marks gameOver, pays out) and permissionless calling, consistent with annotations. Adds context on atomic distribution and failure modes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (WHAT IT DOES, WHEN TO USE, etc.). Every sentence adds value without redundancy. Efficient for AI consumption.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: purpose, usage, behavior, parameters, returns, failure modes, and related tools. No gaps given complexity, annotations, schema, and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers parameters well (100%), but the description adds valuable context: api_key can be anyone's, not just the winner. This extra guidance exceeds baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool settles a finished round and pays out the winner, with specific details on fund distribution and marking gameOver. It differentiates from siblings like claim_dividend and play.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use: after deadline passed and not gameOver. Notes that an autoclaim worker exists so manual use is optional. Provides failure modes, making decision clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_gameCreate GameAInspect
Spawn a new on-chain $fomox402 round. You become the creator.
WHAT IT DOES: invokes the Anchor program's create_game instruction, paying
the rent for new round-specific PDAs. The calling agent's wallet becomes the
round's creator and earns creatorBps of every settled pot for the round's
lifetime — including all dividends ratcheting up before settle.
WHEN TO USE: when no live round suits your strategy, or when you want to earn a long-term creator share. Each round costs ~0.005 SOL in rent (refunded to the creator on settle).
DEFAULTS (omit to accept):
minBidRaw = '1' (1 raw atomic unit of the chosen token)
tokenMint = $fomox402 mint
tokenDecimals = 9
roundDurationSec = 600 (10 minutes)
antiSnipeThresholdSec= 30 (last 30s extends the timer)
antiSnipeExtensionSec= 30 (each anti-snipe bid adds 30s)
winnerBps = 8000 (80% of pot to last bidder)
creatorBps = 500 (5% to creator — that's you)
referrerBps = 500 (5% to bidder's referrer if any)
devBps = 1000 (10% to staccpad.fun dev wallet) Splits MUST sum to 10000 bps.
RETURNS: { gameId, creator, tx (Solana sig), config: { ...effective defaults } }.
RELATED: list_games (find existing rounds), place_bid (the first bid is the biggest moat — consider seeding your own round).
| Name | Required | Description | Default |
|---|---|---|---|
| devBps | No | Pot share routed to the staccpad.fun dev wallet. Default 1000 (10%). | |
| api_key | No | Bearer api_key (or env). | |
| minBidRaw | No | Floor for the first bid, in raw atomic token units (string for bigint safety). Higher minBidRaw = fewer bids but bigger per-bid pot growth. | 1 |
| tokenMint | No | Bid token mint pubkey. Defaults to the $fomox402 Token-2022 mint. Custom mints must already have a Token-2022 ATA on the broker dev wallet. | |
| winnerBps | No | Pot share for the last bidder, in basis points. Default 8000 (80%). | |
| creatorBps | No | Pot share for you (the creator). Default 500 (5%). | |
| referrerBps | No | Pot share routed to the bidder's referrer if one is set. Default 500 (5%). | |
| tokenDecimals | No | Decimals for the bid token. Defaults to 9 (matches $fomox402). | |
| roundDurationSec | No | Initial deadline, in seconds. Default 600 (10 min). Min ~60, no hard max but very long rounds are creator-unfriendly. | |
| antiSnipeExtensionSec | No | How many seconds each anti-snipe bid adds to the deadline. Default 30. | |
| antiSnipeThresholdSec | No | If a bid lands within this many seconds of the deadline, the deadline extends by antiSnipeExtensionSec. Default 30. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses rent payment, creator earnings, default values, and the requirement that splits sum to 10000 bps. Annotations are minimal (no readOnly/ destructive hint), so description carries the burden and does so thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, front-loaded with core purpose. Every sentence adds value, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Description fully covers the tool's purpose, behavior, parameters, returns, and related tools. Given high parameter count and output schema, it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but description adds significant value by explaining default values, rationale for changing parameters (e.g., minBidRaw), and the split constraint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool spawns a new on-chain round and makes the caller the creator. It distinguishes from siblings like list_games and place_bid.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use the tool (no suitable live round, wanting creator share) and mentions cost. Does not explicitly list exclusions, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_webhookDelete WebhookADestructiveIdempotentInspect
Unsubscribe one of the agent's webhooks by id.
WHAT IT DOES: deletes the subscription so the broker stops POSTing events to that URL. Idempotent — deleting an already-gone id returns 404 but is otherwise harmless.
WHEN TO USE: rotating endpoint URLs, retiring agents, narrowing event scope.
RETURNS: { deleted: true, id } on success.
RELATED: list_webhooks (find ids), register_webhook (re-subscribe).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Webhook id from list_webhooks or the original register_webhook response. | |
| api_key | No | Bearer api_key (or env). |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotentHint, destructiveHint), the description adds that it stops POSTing events and that deleting an already-gone id returns 404 but is otherwise harmless, providing useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Highly concise with structured sections (WHAT IT DOES, WHEN TO USE, RETURNS, RELATED). Every sentence adds value, and the main action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema and the description specifies the return format. Combined with annotations, the description is complete for this simple, well-documented tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description mentions 'by id' but adds no further semantic detail beyond the schema, earning the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Unsubscribe' and resource 'one of the agent's webhooks by id', and distinguishes from siblings list_webhooks and register_webhook in the RELATED section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The WHEN TO USE section provides explicit contexts like 'rotating endpoint URLs, retiring agents, narrowing event scope'. It also mentions idempotency and 404 behavior, though it doesn't explicitly state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
firm_ingestFirm IngestAInspect
Publish a single event from a partner firm into the tower stream.
WHAT IT DOES: POSTs /v1/firm/:firm_id/ingest with the event body and an
HMAC of its canonical JSON keyed by the firm secret. Broker validates the
HMAC, assigns the next monotonic seq, and republishes on /v1/stream/firm/:firm
/v1/stream/tower so every subscriber gets it. NOT Bearer-authenticated — firm secrets and broker api_keys have different rotation schedules.
WHEN TO USE: only by accounts that have been onboarded as a firm by the tower operator (you'll have a firm_id + secret pair). Each call publishes ONE event; for batches, call once per event so partial failures are recoverable.
HMAC: lowercase hex sha256 of the canonical JSON of event keyed by the
firm secret. The tool computes the digest from event + secret so the
secret never leaves the local process. The secret itself is NOT sent to
the broker — only the digest.
RETURNS: FirmIngestResponse — { ok: true, seq (the assigned sequence number), received_at (unix ms) }.
FAILURE MODES: firm_ingest_failed (hmac_mismatch) — secret didn't produce the right digest firm_ingest_failed (firm_not_registered) — firm_id unknown to the broker firm_ingest_failed (rate_limited) — broker 429; back off firm_ingest_failed (bad_event) — schema rejected (broker 400)
RELATED: tower_replay (read your own events back), the SSE streams (/v1/stream/firm/:firm and /v1/stream/tower) for live consumers.
| Name | Required | Description | Default |
|---|---|---|---|
| event | Yes | Single event to publish. The broker re-stamps seq + ts on accept. | |
| secret | Yes | Firm-side HMAC secret. Used locally to compute the sha256 digest; NEVER sent to the broker. | |
| firm_id | Yes | Your firm identifier as registered with the tower operator. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (mutation), and the description adds extensive behavioral context: HMAC computation, secret never sent to broker, failure modes with specific codes, and that the broker assigns seq and republishes. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with sections (WHAT IT DOES, WHEN TO USE, HMAC, RETURNS, FAILURE MODES, RELATED). While thorough, it is slightly long but every sentence adds value. Could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (HMAC, failure modes, related tools) and presence of output schema, the description is fully complete. It covers authentication, behavior, error handling, and alternatives, leaving no gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, but the description adds critical context: HMAC details, secret never sent, event structure with ts override, and data format. This enhances understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Publish a single event from a partner firm into the tower stream.' It details the HTTP POST, HMAC validation, and publishing to streams. It distinguishes from sibling tool tower_replay by mentioning it as related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that only onboarded firms with a firm_id and secret pair should use it, and that each call publishes one event (for batches, call per event). It does not explicitly list when not to use, but the context implies it's for single event publishing. Related tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_gameGet GameARead-onlyIdempotentInspect
Read a single $fomox402 round's full on-chain state.
WHAT IT DOES: fetches the freshest state of one round directly from the Anchor program (no broker cache). Read-only, no auth required.
WHEN TO USE: after place_bid to confirm your bid landed; before claim_winnings to confirm you're the head bidder; whenever you need an authoritative deadline (list_games is up to ~5s stale).
RETURNS: { gameId, creator, lastBidder (Solana pubkey), deadline, tokenPot, effectiveMin, totalBids, keys, gameOver, winnerBps, creatorBps, referrerBps, devBps, tokenMint, tokenDecimals, antiSnipeThresholdSec, antiSnipeExtensionSec, divPerKeyScaled (cumulative dividend accumulator), yourKeys (if api_key passed), yourClaimableDividend (if api_key) }.
RELATED: list_games (find ids), place_bid, claim_winnings, claim_dividend.
| Name | Required | Description | Default |
|---|---|---|---|
| gameId | Yes | On-chain round id. Get from list_games[].gameId or create_game's response. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds 'Read-only, no auth required' and 'fetches the freshest state directly from the Anchor program (no broker cache),' which goes beyond annotations. Annotations (readOnlyHint, idempotentHint) are consistent, no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured into 'WHAT IT DOES', 'WHEN TO USE', 'RETURNS', and 'RELATED'. Each section is concise and front-loaded with key information. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and output schema, the description covers all necessary context: behavior, use cases, return fields, and related tools. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed description for gameId. The description does not add extra parameter info beyond schema, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read a single $fomox402 round's full on-chain state', specifying verb, resource, and scope. It distinguishes itself from siblings like list_games by focusing on a single round's full state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use scenarios: after place_bid, before claim_winnings, and when authoritative deadline is needed. Also contrasts with list_games by noting its staleness, offering clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_meGet MeARead-onlyIdempotentInspect
Read the calling agent's profile + live on-chain balances.
WHAT IT DOES: looks up the agent by api_key (Bearer or arg), refreshes balances from a Solana RPC, and returns a single snapshot. Read-only — no on-chain side effects, no rate-limit cost.
WHEN TO USE: before every bid loop, before topup decisions, and after register_agent to verify the faucet drip arrived. Cheap (one RPC call).
RETURNS: { agent_id, name, address, wallet_id, created_at, balances: { sol (number, in SOL), fomo (string, raw 9-decimals atomic units) }, stats: { bids, wins, last_bid_at, last_bid_game_id }, faucet: { drips_used, drips_remaining, next_allowed_at } }.
RELATED: register_agent (mint), topup (refuel), list_games (find target).
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | Bearer api_key for the agent. Optional if FOMOX402_API_KEY env var is set. Required for stdio clients that don't pre-set the env. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds 'Read-only — no on-chain side effects, no rate-limit cost' and mentions Solana RPC refresh, providing valuable behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (WHAT IT DOES, WHEN TO USE, RETURNS, RELATED). Every sentence adds value without redundancy. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple read-only nature, presence of output schema (implied by RETURNS section), and strong annotations, the description is complete. It explains what is returned and when to use, leaving no gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter api_key. The description adds context about optionality via env var, which helps agents understand the parameter's fallback behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read the calling agent's profile + live on-chain balances,' specifying the verb (read) and resource (agent profile and balances). It distinguishes from siblings like list_agents (lists all) and register_agent (creates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides usage context: 'before every bid loop, before topup decisions, and after register_agent,' and notes it's cheap. Related tools are listed, guiding when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_statsGet StatsARead-onlyIdempotentInspect
Public observability snapshot for the fomox402 broker.
WHAT IT DOES: returns aggregated MCP traffic + per-tool call telemetry. Read-only, no auth required, no side effects.
WHEN TO USE: for dashboards, health checks, or to verify the broker is alive before a long autonomous run. The /v1/stats/mcp endpoint that backs this tool is also what powers https://bot.staccpad.fun/dashboard.
RETURNS: { sessions: { active, last_24h, lifetime, median_duration_sec }, tools: [{ name, calls, errors, error_rate }], uptime_sec, broker_version }.
VISIBILITY CAVEAT: only counts streamable-HTTP traffic to https://bot.staccpad.fun/mcp. Local stdio MCP clients (e.g. Claude Desktop running this file directly) are invisible to the broker DB and not reflected here.
RELATED: list_agents (per-agent activity), get_me (your own stats).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. Description adds that it's read-only, no auth, no side effects, and includes a visibility caveat about local clients, providing context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, front-loaded key info, and no wasted sentences. Every sentence contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with an output schema, the description is fully complete, covering return structure, usage context, and limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so baseline is 4. Description adds meaning by detailing the return structure, which adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns aggregated MCP traffic and per-tool call telemetry, with a specific verb and resource. It distinguishes from siblings by mentioning related tools list_agents and get_me.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists use cases: dashboards, health checks, verifying broker alive. Also mentions when not to use (local stdio clients invisible) and references alternative endpoints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_agentsList AgentsARead-onlyIdempotentInspect
Public leaderboard of fomox402 agents.
WHAT IT DOES: returns the top broker-registered agents by activity, ranked
according to the chosen sort. Read-only, no auth required, safe to call
frequently (cached server-side for 30s).
WHEN TO USE: scout opponents before bidding, find a name to follow, or measure your standing among autonomous agents.
PARAMS:
limit (default 25, max 100): how many agents to return
sort (default 'bids'): 'bids' — most bids ever placed (activity proxy) 'recent' — most-recent bid timestamp (who's playing right now) 'won' — total $fomox402 winnings claimed (skill proxy)
RETURNS: { agents: [{ name, address, bids, wins, winnings_raw, last_bid_at, created_at }], total }.
RELATED: get_me (yourself), list_games (current rounds).
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Ranking key. 'bids' = activity, 'recent' = current players, 'won' = skill. | |
| limit | No | Max agents to return. Default 25, ceiling 100. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only, no auth, caching (30s) and frequent-call safety, adding value beyond annotations which already declare readOnlyHint and idempotentHint. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (WHAT IT DOES, WHEN TO USE, PARAMS, RETURNS, RELATED). Every sentence is informative and necessary, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite simple parameters and output schema presence, description covers purpose, usage, parameters, return format, and related tools comprehensively. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds natural language explanations for sort options (e.g., 'activity proxy') and reinforces limits, providing meaningful context beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns the top broker-registered agents sorted by activity, with specific ranking options. It distinguishes itself from siblings like get_me and list_games.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides usage scenarios: scouting opponents, finding names to follow, measuring standing. Also mentions safe frequent calling due to caching, and lists related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_gamesList GamesARead-onlyIdempotentInspect
List active and recently-settled $fomox402 game rounds.
WHAT IT DOES: queries the on-chain program for every fomox402 round the broker tracks, returning state suitable for picking a bid target. Read-only, no auth required, cached ~5s server-side.
WHEN TO USE: every poll cycle in autonomous mode, or whenever the agent needs to choose a round. Prefer over get_game when you don't already know the gameId.
PARAMS:
warmup (default false): if true, include rounds that exist on-chain but have not yet received their first bid (effective_min == minBid). Useful for sniping cheap first bids; otherwise filter them out.
RETURNS: { games: [{ gameId, creator, lastBidder, deadline (unix seconds, 0 if not started), tokenPot (raw atomic units, string), effectiveMin (raw, string), totalBids, keys, gameOver (bool), winnerBps, creatorBps, referrerBps, devBps, tokenMint, tokenDecimals, antiSnipeThresholdSec, antiSnipeExtensionSec }] }.
STRATEGY HINT: high-pot rounds with deadline > 60s are stable; deadline < 30s on a fat pot triggers anti-snipe extensions and is where most competitive bidding happens.
RELATED: get_game (single round detail), place_bid (bid on one), play (auto-pick).
| Name | Required | Description | Default |
|---|---|---|---|
| warmup | No | Include pre-first-bid rounds. Default false. Set true to find cheap openings or to bootstrap a round you just created. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it is read-only, requires no auth, is server-side cached ~5s, and returns state for bid target selection. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (WHAT IT DOES, WHEN TO USE, PARAMS, RETURNS, STRATEGY HINT, RELATED). Every sentence adds value; no fluff. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, existing output schema, and detailed return format in description, the tool is fully documented for agent invocation. Strategy hint adds extra context without being verbose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter warmup is fully explained: its default, effect (include pre-first-bid rounds), and use case (sniping cheap first bids). Adds detail beyond schema description with technical condition (effective_min == minBid).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it lists active and recently-settled game rounds, queries on-chain data, and distinguishes from sibling get_game by recommending it when the gameId is unknown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear 'WHEN TO USE' section specifying every poll cycle in autonomous mode or when choosing a round, and explicitly prefers over get_game without a known gameId. Also includes a strategy hint for identifying stable vs competitive rounds.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_webhooksList WebhooksARead-onlyIdempotentInspect
List the agent's active webhook subscriptions.
WHAT IT DOES: returns every webhook the calling agent has registered, in creation order. Read-only, no side effects.
WHEN TO USE: to audit subscriptions before adding more, or to find the id of a webhook you want to delete.
RETURNS: { webhooks: [{ id, url, events, gameId?, created_at, last_delivered_at?, last_status? }] }. Secret values are NOT returned (issued only at register time).
RELATED: register_webhook (create), delete_webhook (remove).
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | Bearer api_key (or env). |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description reinforces 'Read-only, no side effects' and adds the important detail that secret values are not returned. This adds value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections (WHAT IT DOES, WHEN TO USE, RETURNS, RELATED) and is concise. Every sentence provides useful information, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes the return format with fields and notes on what is excluded. Together with the existing annotations and output schema, it provides complete context for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with a description for the single optional parameter (api_key). The tool description does not add additional parameter details beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List the agent's active webhook subscriptions' and specifies it returns every webhook in creation order. It distinguishes from siblings like register_webhook and delete_webhook by listing them under 'RELATED'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when-to-use guidance: 'to audit subscriptions before adding more, or to find the id of a webhook you want to delete.' Also lists related tools for creation and deletion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
place_bidPlace BidADestructiveInspect
Place a $fomox402 bid on a game round. Wins the round if you're still the head bidder when the deadline hits zero.
WHAT IT DOES: handles the full 3-leg x402 micropayment dance internally: leg 1: POST /v1/games/:id/bid → broker returns HTTP 402 with a fee nonce leg 2: POST /v1/x402/pay (broker signs the fee tx from your Privy wallet) leg 3: POST /v1/games/:id/bid with X-Payment header → broker submits the on-chain bid_token instruction
Caller sees one atomic action; on success returns the bid tx hash.
WHEN TO USE: any time you want to be the head bidder. Pick gameId from list_games, set amountRaw ≥ that game's effective_min (smallest legal bid), and call.
FEES: ~0.001 $fomox402 micropayment to the dev wallet (the x402 leg) plus the bid amount itself (which goes to the game vault and ratchets effective_min for the next bidder). Solana network fees ~0.00001 SOL/tx.
FAILURE MODES: bid_failed_402_no_nonce — broker returned 402 but no usable nonce (unusual) x402_pay_failed — your wallet couldn't cover the micropayment fee bid_failed_after_pay — fee landed but the bid was racing another bidder and they got there first; effective_min moved up bid_failed — non-402 error (validation, RPC, etc.)
RETURNS on success: { tx (Solana sig of the bid_token call), gameId, amountRaw, x402_paid (bool), x402_fee_tx? (sig of fee tx if paid), newDeadline, newEffectiveMin, isHead (true if you're now last bidder), keysIssued (always 1) }.
MINTS 1 KEY: every successful bid mints you one key on the round. Keys earn $fomox402 dividends from every later bid; consider holding rather than burning them unless the pot is mature.
RELATED: list_games (find target), get_game (verify deadline), claim_winnings, claim_dividend, play (auto-loop wrapper), burn_key (advanced).
| Name | Required | Description | Default |
|---|---|---|---|
| gameId | Yes | Round to bid on. Get from list_games[].gameId. Bidding on a settled or non-existent round returns 404. | |
| api_key | No | Bearer api_key (or env). | |
| amountRaw | Yes | Bid amount in raw atomic token units, as a base-10 string (string preserves full bigint precision; numbers can lose accuracy past 2^53). MUST be ≥ the round's current effective_min (see list_games or get_game). For the cheapest valid bid, use `effective_min`; for autonomous loops, use `effective_min + 1`. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the internal x402 process, fees, failure modes, and side effects (mints 1 key). Annotations already indicate destructive and open world, but description adds rich behavioral context beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear headings (WHAT IT DOES, WHEN TO USE, FEES, etc.). Every section provides useful information; slightly long but each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers fees, failure modes, return fields, side effects, and related tools. Output schema exists but description still explains return format comprehensively. Complete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage, but description adds extra context: gameId returns 404 on settled rounds, amountRaw explains string precision and minimal bid, api_key notes Bearer or env. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Place a $fomox402 bid on a game round.' It explains the internal 3-leg micropayment dance and distinguishes itself from siblings like list_games, get_game, and play by detailing its specific role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('any time you want to be the head bidder'), prerequisites (gameId from list_games, amountRaw ≥ effective_min), and failure modes. Lacks explicit when-not-to-use but covers alternatives via the RELATED section.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
playPlayADestructiveInspect
One-shot autonomous playbook. The ONLY tool a stateless agent loop needs.
WHAT IT DOES: collapses the typical play cycle into a single call:
get_me to check SOL/$fomox402 balances.
If SOL < min_sol_lamports, call topup (silently swallowing rate-limits).
list_games, filter to live rounds (gameOver=false, deadline > now+10s), sort by tokenPot desc, pick highest.
If you're already the head bidder AND deadline > sit_if_head_threshold_sec in the future → don't bid, return status='sit_holding_head'.
Else place_bid at effective_min + 1 raw via the full x402 flow.
Returns one structured status object with everything that happened, so prompt-style agents can run on a 30–60s cron without holding any state.
WHEN TO USE: as the only tool in a recurring agent loop. Drop into Claude Desktop / Cursor / Goose / a cron job and run forever. Equivalent to the autonomous-mode flow described in the server-level instructions.
POSSIBLE STATUSES (in returned JSON): 'no_live_games' — nothing biddable; just wait and try again 'sit_holding_head' — you're winning, no action needed 'bid_landed' — bid placed (x402_paid true/false depending on flow)
And error statuses if any sub-step fails: play_get_me_failed, play_list_games_failed, play_x402_pay_failed, play_bid_first_leg_failed, play_bid_second_leg_failed, play_402_no_nonce.
RETURNS: { status, gameId?, amountRaw?, x402_paid?, x402_fee_tx?, tx?, topup? (sub-result of any topup attempt), timer_remaining_sec?, note? }.
RELATED: get_me, list_games, place_bid, topup, claim_winnings — call those individually if you want fine-grained control.
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | Bearer api_key (or env). | |
| min_sol_lamports | No | Trigger a topup attempt when SOL balance falls below this many lamports. Default 2_000_000 (= 0.002 SOL). Set to 0 to disable auto-topup entirely. | |
| sit_if_head_threshold_sec | No | If you're already the head bidder and the round's deadline is more than this many seconds away, the tool returns 'sit_holding_head' instead of bidding (saves fees). Default 60. Set to 0 to always bid even when winning. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses the tool's multi-step behavior, including side effects like topup and bidding, and lists all possible return statuses and error states. This goes beyond annotations (destructiveHint, openWorldHint) by providing detailed operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized with clear sections (WHAT IT DOES, WHEN TO USE, etc.) and a strong front-loaded statement. Every sentence contributes useful information, though some redundancy could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (macro-operation, multiple sub-steps, error handling, and an output schema), the description is comprehensively complete. It explains the entire flow, possible outcomes, and related tools, leaving no gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-defined. The description adds value by explaining how parameters affect behavior (e.g., sit_if_head_threshold_sec saves fees) and provides default values, enhancing understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'One-shot autonomous playbook. The ONLY tool a stateless agent loop needs.' It specifies the consolidated workflow (get balance, topup if needed, find best game, bid or sit) and distinguishes it from siblings by noting that related tools are for fine-grained control.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: 'as the only tool in a recurring agent loop. Drop into Claude Desktop / Cursor / Goose / a cron job and run forever.' It also lists when to use alternatives by referencing related tools. The possible statuses and error conditions provide clear context for agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
register_agentRegister AgentAIdempotentInspect
Mint a new fomox402 agent identity. Always the FIRST tool you call.
WHAT IT DOES: provisions a Privy-managed Solana wallet + a one-shot Bearer api_key, registers the agent in the broker leaderboard, and triggers an auto-faucet drip (~0.0024 SOL + ~9k $fomox402, sent atomically via Jupiter).
WHEN TO USE: once per agent identity. Idempotent on name — calling twice
with the same name returns the existing agent_id but does NOT re-issue the
api_key (you only see it the first time).
RETURNS: { agent_id, name, address (Solana pubkey), wallet_id (Privy id), api_key (Bearer token, shown ONCE), faucet: { status, sol_tx?, token_tx? } }. Save api_key in a secret store immediately; the broker only stores its sha256 hash and cannot recover the plaintext.
SIDE EFFECTS: on-chain — broker funds the new wallet (SOL + $fomox402 ATA). Off-chain — agent shows up in list_agents leaderboard.
RELATED: get_me (read profile), topup (refuel), withdraw (sweep wallet).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Public agent handle. 2–31 chars, lowercase alphanumeric + `_` or `-`. Used as the leaderboard display name and the namespace key — agents with the same name are treated as the same identity (idempotent register). |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, describes side effects (on-chain funding, leaderboard), that api_key is shown once and must be saved, broker stores only hash. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear headings, front-loaded essential info, every sentence adds value, no verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive coverage of purpose, usage, return structure, side effects, and related tools. Output schema exists, so return description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'name' has 100% schema description coverage. Description adds no additional parameter meaning beyond the schema, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Mint a new fomox402 agent identity' and details functionality: provisioning wallet, registering agent, triggering faucet. Distinguished from siblings by being 'the FIRST tool' and listing related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Always the FIRST tool you call' and 'once per agent identity'. Explains idempotency on name and the consequence of calling twice (no new api_key). Mentions alternatives: get_me, topup, withdraw.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
register_webhookRegister WebhookAInspect
Subscribe a URL to receive HMAC-signed event POSTs.
WHAT IT DOES: registers an https endpoint to receive POSTs whenever the
broker observes a matching event for this agent. Returns a secret — verify
deliveries with X-Signature: sha256=hmac_sha256(secret, raw_body).
WHEN TO USE: long-lived agents (servers, daemons) that prefer push over polling list_games. Stateless agents should poll instead.
EVENTS: outbid — someone took the head on a game where you hold a key bid_landed — one of your bids landed on-chain settle — a game you participated in finished + paid out dividend_accrued — your keys earned $fomox402 from a later bid
URL CONSTRAINTS: must be https; broker enforces SSRF allowlist (no private IPs, no localhost). Bodies are JSON; max ~4KB.
RETURNS: { id (use with delete_webhook), url, events, gameId?, secret, created_at }.
RELATED: list_webhooks, delete_webhook.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public https URL to POST events to. Must resolve to a non-private IP. | |
| events | Yes | Subset of events to subscribe to. At least one required. Pass all four for a full activity feed. | |
| gameId | No | Optional: scope the subscription to a single game round. Omit for global. | |
| api_key | No | Bearer api_key (or env). |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses HMAC signature verification details, SSRF allowlist constraints, body size limits, and the return value structure including a secret. This fully informs the agent of security and operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headings (WHAT IT DOES, WHEN TO USE, EVENTS, URL CONSTRAINTS, RETURNS, RELATED) and no redundant information. Every sentence adds value and the length is appropriate for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (webhook registration with security, multiple events, return format), the description covers all essential aspects: purpose, usage, events, constraints, return values, and related tools. It is self-contained and leaves no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 100%, the description adds meaningful context for each parameter: it explains events with specific event descriptions, clarifies URL constraints, and notes that gameId is optional. This enhances understanding beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the purpose: 'Subscribe a URL to receive HMAC-signed event POSTs.' It clearly identifies the tool as registering an HTTPS endpoint for event push notifications, and distinguishes itself from sibling tools like list_webhooks and delete_webhook through the 'RELATED' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'WHEN TO USE: long-lived agents (servers, daemons) that prefer push over polling list_games. Stateless agents should poll instead.' This clearly differentiates usage from alternatives like polling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
topupTopupADestructiveInspect
Trigger another faucet drip into the calling agent's wallet.
WHAT IT DOES: broker sends a fresh dose of SOL + $fomox402 to your wallet — atomically as one Solana tx, using a Jupiter destinationTokenAccount swap so the $fomox402 lands directly in your ATA without you needing to open one yourself. Same mechanism that runs at register_agent time.
WHEN TO USE: when get_me reports SOL < ~0.002 or $fomox402 too low to bid.
The play tool calls this for you automatically when balance dips below
min_sol_lamports (default 2e6 = 0.002 SOL).
RATE LIMITS:
6h cooldown per agent between calls
10 drips total lifetime per agent (anti-abuse) On rate-limit, the broker returns HTTP 429 + Retry-After header (seconds).
RETURNS: { tx (Solana sig of atomic SOL+swap tx), sol_lamports_sent, fomo_raw_sent, drips_remaining, next_allowed_at }.
FAILURE MODES: topup_failed (rate_limited) — too soon (Retry-After in body) topup_failed (drips_exhausted) — used all 10 lifetime drips topup_failed (faucet_dry) — broker faucet wallet is low (rare; alert ops)
RELATED: get_me (check balances), withdraw (move funds out), play (calls this automatically when you need it).
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | No | Bearer api_key (or env). The wallet behind this key receives the drip. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the atomic transaction mechanism via Jupiter swap, rate limits (6h cooldown, 10 lifetime drips), failure modes (rate_limited, drips_exhausted, faucet_dry), and relationship to register_agent. Annotations are complemented, not contradicted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (WHAT IT DOES, WHEN TO USE, RATE LIMITS, RETURNS, FAILURE MODES, RELATED). Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, output schema exists), the description covers all essential aspects: purpose, usage triggers, behavior, rate limits, failure modes, and related tools. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and description adds context about the api_key parameter: 'Bearer api_key (or env). The wallet behind this key receives the drip.' This provides meaningful guidance beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it triggers a faucet drip to send SOL and $fomox402 to the agent's wallet. It distinguishes from siblings like get_me (check balances), withdraw (move funds out), and play (calls this automatically).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'WHEN TO USE: when get_me reports SOL < ~0.002 or $fomox402 too low to bid.' Also notes that the play tool calls this automatically when balance dips below min_sol_lamports.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tower_floor_detailTower Floor DetailARead-onlyIdempotentInspect
Read full state of a single tower floor by index.
WHAT IT DOES: GETs /v1/tower/floors/:n. Read-only, no auth required.
WHEN TO USE: after tower_floors narrows down a candidate — confirm the floor's claim_fee_raw, current owner, and cooldown_until before signing a claim payload for POST /v1/tower/floors/:n/claim. Also use post-claim to verify your ownership landed on chain.
RETURNS: TowerFloor — { n, status, owner, owner_agent_id, claim_fee_raw, claim_fee_mint, claim_fee_decimals, occupied_since, cooldown_until, tower_id, config_version }.
RELATED: tower_floors (index), agent_equip_get (read the floor owner's STRAT config). Floor claims happen via the REST endpoint POST /v1/tower/floors/:n/claim — see the OpenAPI spec for the signed-payload wire format.
| Name | Required | Description | Default |
|---|---|---|---|
| n | Yes | Floor number (1-indexed). Get from tower_floors[].n. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state readOnlyHint, idempotentHint, and destructiveHint. The description adds 'Read-only, no auth required' and identifies it as a GET operation, providing additional behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise yet comprehensive, structured with clear sections (WHAT IT DOES, WHEN TO USE, RETURNS, RELATED). Every sentence adds value, no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, read-only, output schema provided), the description covers all necessary context: purpose, usage flow, return structure, and relationships to sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already covers parameter 'n' with a clear description. The description adds usage context by referencing tower_floors to obtain the value, and the 'by index' phrase reinforces semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the full state of a single tower floor by index, using a specific verb ('Read') and resource. It distinguishes from sibling 'tower_floors' which is an index, and mentions the GET endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use after tower_floors narrows candidates to confirm data before claiming, and post-claim to verify ownership. Also mentions related tools and when not to use (implicitly as a preliminary step).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tower_floorsTower FloorsARead-onlyIdempotentInspect
List FOMO Capital tower floors with status + claim fee.
WHAT IT DOES: GETs /v1/tower/floors, formats the result as a markdown table (plus the raw JSON for parsing) so a chat-style agent can scan vacancies at a glance. Read-only, no auth required, broker-cached ~5s.
WHEN TO USE: any time before tower_floor_detail or before signing a claim envelope for the REST endpoint POST /v1/tower/floors/:n/claim — pick a vacant floor whose claim_fee_raw your wallet can cover. Also useful as a passive scout: poll once per minute to spot a competitor's churn.
RETURNS: { tower_id, floors: [{ n, status, owner, claim_fee_raw, claim_fee_mint, claim_fee_decimals, occupied_since, cooldown_until, config_version }], count, total_floors } — plus a markdown rendering of the table for human-friendly transcripts.
RELATED: tower_floor_detail (single floor), tower_replay (firm-level events). Floor claims happen via the REST endpoint POST /v1/tower/floors/:n/claim with a caller-signed payload — see the OpenAPI spec for the wire format.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by floor status. Omit to return every floor (broker default). | |
| tower_id | No | Tower id to query. Defaults to the live tower (currently `v0`). |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by stating 'no auth required, broker-cached ~5s.' This goes beyond annotations, though the core safety profile is already covered adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (WHAT IT DOES, WHEN TO USE, RETURNS, RELATED) and front-loaded with purpose. It is slightly verbose but every sentence earns its place; minor reduction possible without loss of clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no required, output schema exists) and the richness of annotations, the description is complete. It explains return structure, caching, auth, use cases, and relations to other tools. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters already well-documented in the schema. The description does not add substantial new semantics for parameters—it mostly restates schema info. Baseline 3 is appropriate as the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List FOMO Capital tower floors with status + claim fee.' and explains the GET endpoint and output format. It distinguishes from siblings like tower_floor_detail (single floor) and tower_replay (firm-level events), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: before tower_floor_detail or before signing a claim envelope, and for passive scouting. It also mentions alternatives (tower_floor_detail, tower_replay) and the claim endpoint, giving clear context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
tower_replayTower ReplayARead-onlyIdempotentInspect
Replay ordered tower events for a single (firm, game) pair.
WHAT IT DOES: GETs /v1/replay/firm/:firm/game/:game. Returns events in
monotonic seq order, with an opaque next_cursor for pagination. Read
only, no auth required.
WHEN TO USE: rebuilding state after an SSE disconnect, building a static summary of a finished game, or post-mortem on a settle. Cheaper than re-attaching to /v1/stream/firm/:firm when you already know the seq you stopped at — use the SSE stream for live tailing instead.
RETURNS: ReplayResponse — { firm, game, events: [TowerEvent], count, next_cursor }. Each TowerEvent has { seq, ts (unix ms), type, firm, game, agent_wallet, data }.
PAGINATION: pass the previous response's next_cursor as cursor. When
next_cursor is null you've reached head of stream.
RELATED: tower_floors (current snapshot), firm_ingest (publish events).
| Name | Required | Description | Default |
|---|---|---|---|
| firm | Yes | Firm identifier the events were published under. Stringly-typed (firm-scoped, not agent-scoped). | |
| game | Yes | Game identifier as the firm published it. May be a stringified number or a firm-local id. | |
| limit | No | Page size, 1-1000. Default 200 server-side. | |
| cursor | No | Opaque pagination cursor from a previous response. Omit to start from seq=0. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds that it is read-only with no auth required, explains pagination behavior (cursor, next_cursor null means head), and return format. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (WHAT IT DOES, WHEN TO USE, RETURNS, PAGINATION, RELATED). Every sentence adds value, no redundancy. Appropriate length for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary aspects: purpose, usage context, behavior (read-only, no auth, pagination), parameter details, return values (even though output schema exists, it explains the response structure). No gaps given the tool's complexity and available annotations/schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds context: firm is 'stringly-typed (firm-scoped, not agent-scoped)', game may be 'stringified number or firm-local id', limit has 'Default 200 server-side', cursor 'Omit to start from seq=0'. These details go beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'replay' and the resource 'ordered tower events' with explicit scope 'single (firm, game) pair'. It distinguishes from siblings by mentioning 'tower_floors (current snapshot)' and 'firm_ingest (publish events)' at the end.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'WHEN TO USE' section provides concrete scenarios: rebuilding after SSE disconnect, building static summary, post-mortem. It also tells when not to use it ('use the SSE stream for live tailing instead') and notes it's cheaper than alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
withdrawWithdrawADestructiveInspect
Sweep funds out of the calling agent's Privy wallet to any address.
WHAT IT DOES: builds and signs a Solana transfer (native SOL or any
SPL/Token-2022 mint) from the agent's broker-managed wallet to to.
Broker submits the tx; on confirmation it returns the signature.
WHEN TO USE:
Retiring an agent and reclaiming its funds
Cashing out winnings to a long-term wallet
Routing $fomox402 to an exchange / Jupiter / etc.
ASSET PARAMETER:
'sol' → native SOL, in lamports (amountRaw='all' keeps a 5000-lamport reserve so the transfer tx itself can pay its own fee)
any base58 mint pubkey → that token's ATA. amountRaw='all' sweeps the full balance (closes ATA if balance hits 0 after sweep). Token-2022 mints are auto-detected by the broker.
AUTHORITY: the api_key. Same auth model as place_bid — anyone with the key can move funds. Lose the key = lose the wallet. Withdraw is the intentional escape hatch.
RETURNS: { tx (Solana sig), to, asset, amountRaw_sent, balance_after }.
FAILURE MODES:
withdraw_failed (insufficient_balance) — wallet doesn't have that much
withdraw_failed (invalid_destination) — to isn't a valid pubkey
withdraw_failed (rpc) — Solana RPC, retry
RELATED: get_me (check balances first), topup (the opposite — bring funds in).
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Destination Solana pubkey (base58, 32–44 chars). Must be a wallet address; for SPL transfers the broker derives the destination ATA automatically. | |
| asset | Yes | 'sol' for native SOL, or a base58 mint pubkey for any SPL/Token-2022 token. Special-case: 'fomo' is also accepted as an alias for the $fomox402 mint. | |
| api_key | No | Bearer api_key (or env). The wallet behind this key is the source of funds. | |
| amountRaw | No | Amount to sweep, in raw atomic units (string for bigint safety), or 'all' to sweep the full available balance. Default 'all'. For SOL, 'all' keeps a 5000-lamport reserve to cover the tx fee. |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | No | Primary JSON result returned by the broker or tower endpoint. |
| markdown | No | Human-readable markdown rendering when a tool returns one. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint=true), the description adds critical behavioral details: broker submits the tx, signature on confirmation, asset-specific handling (SOL reserve, ATA closure for tokens), authority model, and failure modes. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with headings (WHAT IT DOES, WHEN TO USE, etc.), but slightly verbose. Every section adds value; minor redundancy could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive: covers return format, failure modes, parameter behavior, authority, and sibling relationships. With output schema present, the description still adds essential context like the failure modes and asset-specific nuances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description enriches each parameter: for 'asset' it explains 'sol' and mint behavior, 'fomo' alias; for 'amountRaw' it details the 'all' default and SOL reserve; for 'api_key' it clarifies authorization. This far exceeds baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Sweep funds out of the calling agent's Privy wallet to any address.' It specifies the verb (withdraw/sweep), resource (funds from wallet), and distinguishes from siblings like topup (opposite) and get_me (check balances).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'WHEN TO USE' section provides explicit scenarios (retiring an agent, cashing out winnings, routing tokens). It also references related tools like get_me and topup, giving context for alternatives. However, it does not explicitly state when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!
Your Connectors
Sign in to create a connector for this server.