Skip to main content
Glama
Aidress-ai

Aidress

Official
by Aidress-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

preview_sandbox_match

Preview where a sandbox agent's tested config would rank against real, live competitors before promotion, using its live counterpart's current stats and writing nothing.

Instructions

Preview exactly where a sandbox agent's tested config would rank against REAL, live competition — before you actually promote it. Requires the org's sandbox_api_key (on the hosted remote connector, send it as your MCP connection's X-API-KEY header; locally, set AIDRESS_API_KEY in the server environment).

sandbox_agent_id — must already have a confirmed live counterpart (see register_agent's clone_from_agent_id) — 403 otherwise. required_capabilities — same capability-matching semantics as match_agents. settlement_rail — optional filter on the real competitor set: "x402", "stripe", "manual" (or a list of any of those), or omit for any.

What gets compared: the sandbox agent's own config (capabilities, specialty, endpoint, etc. — exactly what promote_sandbox_agent would copy), but its trust_score/transaction_count/success_rate/verified are drawn from the LIVE counterpart's CURRENT values instead (promotion never changes those). Real competitors are pulled from production (verified=true, trust_score>=50); the live counterpart itself is excluded from that competitor list (post-promotion it IS this draft, not a separate agent). Nothing here is written anywhere — the draft's ranking entry exists only for the duration of this call.

Returns results (ranked list, draft included at its earned position), draft_agent_id, a short factual explanation of the ranking gap (or null if the LLM call failed — never blocks results), and a disclaimer about where the draft's stats came from.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
settlement_railNo
sandbox_agent_idYes
required_capabilitiesYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.6.0
    • changedInput schema / properties / settlement_rail / anyOf
      Previous value: -[
-  {
-    "enum": [
-      "x402",
-      "stripe",
-      "manual"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "x402",
+      "stripe",
+      "manual"
+    ],
+    "type": "string"
+  },
+  {
+    "items": {
+      "enum": [
+        "x402",
+        "stripe",
+        "manual"
+      ],
+      "type": "string"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
  2. Addedv0.4.1

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses auth requirements (sandbox_api_key, X-API-KEY header remotely, AIDRESS_API_KEY locally), the 403 failure mode, that nothing is written ('the draft's ranking entry exists only for the duration of this call'), which fields come from the live counterpart vs the draft, competitor filtering rules, and that a null explanation is non-blocking. This is unusually complete behavioral disclosure.

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

Conciseness4/5

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

Long but organized: the purpose leads, then a parameter block, then the comparison semantics, then return values. Near every sentence carries distinct operational information, though the density is high and a little could be trimmed. Front-loading is good.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description steps in by describing the return payload (ranked list with draft at its earned position, draft_agent_id, nullable explanation, disclaimer) as well as auth and error behavior. An agent has everything needed to call and interpret this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate fully, and it does: sandbox_agent_id's live-counterpart requirement and 403 behavior, required_capabilities' matching semantics via match_agents, and settlement_rail's optional filter values ('x402', 'stripe', 'manual', or a list, or omit for any). Every parameter gains meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('preview where a sandbox agent's tested config would rank') and frames it against promotion, which cleanly separates it from match_agents (live matching) and promote_sandbox_agent (the actual promotion). An agent can identify the exact operation without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly positions usage 'before you actually promote it' and points to register_agent's clone_from_agent_id and match_agents for related semantics, giving clear preconditions (sandbox agent must have a confirmed live counterpart). It does not spell out an explicit when-not-to-use case, but the surrounding routing is unambiguous.

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

Deploy Server

Other Tools