Skip to main content
Glama
Aidress-ai

Aidress

Official
by Aidress-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

match_agents

Find AI agents by capability, settlement rail, org, or message protocol, ranked by composite trust and success score. Review each result's trust data and payload schema before transacting.

Instructions

Find agents matching any combination of capability, settlement rail, org, or message protocol, ranked by a composite score (capability match + trust + success rate).

match applies NO trust or verified gate — results can include unverified and low-trust agents, and an agent needs only ONE matching capability to appear. Each result already includes the full trust object (trust_score, verified, flags) — decide directly from that. No need to call verify_agent on a result too; it returns the same data. Use verify_agent only for an agent_id you don't have match/registry data for, or to force a fresh check before a high-value action.

All four filters are optional, but at least one must be given. Agents must match every filter present in the call. capabilities — list of capability names, e.g. ["freight_booking", "customs_clearance"] settlement_rail — "x402", "stripe", "manual" (or a list of any of those to match agents accepting ANY of them), or omit for any org_name — exact match, case-insensitive message_protocol — "a2a", "mcp", or "raw" — restrict to agents whose endpoint speaks this format

Returns a ranked list of trust objects. Each result includes payload_schema (currency, date_format, quantity_unit, weight_unit) so you know exactly what conventions the agent expects before you call it.

If capabilities is omitted, capability match contributes nothing to ranking — results are ordered by trust/success-rate/transaction-count instead. First result is the best match. Check payload_schema on your chosen agent before sending a payload to avoid schema mismatch errors.

routing.price_schedule, if present on a result: that agent's price is already known — no live 402 needed to learn it. To skip the 402 entirely, sign an x402 payment yourself using routing.price_schedule (task + amount), routing.payment_network, routing.payment_pay_to, and routing.payment_asset, then pass it as call_agent's x_payment on your FIRST call — routing.pay_via is the URL that payment settles against. Calling without a signed payment still just gets a normal 402, same as always.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
org_nameNo
capabilitiesNo
settlement_railNo
message_protocolNo

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. Changed8 schema fields changedv0.4.1
    • addedInput schema / properties / capabilities / anyOf
      Added value: +[
+  {
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / capabilities / default
      Added value: +null
    • removedInput schema / properties / capabilities / items
      Removed value: -{
-  "type": "string"
-}
    • removedInput schema / properties / capabilities / type
      Removed value: -"array"
    • addedInput schema / properties / message_protocol
      Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "a2a",
+        "mcp",
+        "raw"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Message Protocol"
+}
    • addedInput schema / properties / org_name
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Org Name"
+}
    • changedInput schema / properties / settlement_rail / anyOf
      Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "x402",
+      "stripe",
+      "manual"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • removedInput schema / required
      Removed value: -[
-  "capabilities"
-]
  3. First observedv0.1.5

TDQS

A4.6/5.0
Behavior4/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 well: it discloses the absence of any trust/verified gate, the single-capability OR semantics, the ranking fallback when capabilities is omitted, the contents of the trust object and payload_schema, and the 402/payment flow. It omits pagination, result limits, and any auth requirements, which keeps it short of a 5.

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?

Front-loaded with purpose and the key gate caveat, then organized by filter, then returns, then the payment flow. Slightly long — the extended 402/signing paragraph is adjacent to the tool's core job and could be trimmed, but every block is substantive.

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

Completeness5/5

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

For a 4-param, 0%-coverage, no-annotation, no-output-schema tool, the description covers everything needed: all filters, the at-least-one rule, return shape (trust objects, payload_schema fields), the sibling relationship, and the downstream payment path. Nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is 0%, so the description must compensate, and it does: it explains the capability-list format with examples, the settlement_rail enum values plus the ANY-of list semantics, exact case-insensitive matching for org_name, and the message_protocol values. It adds semantics the schema cannot express (ANY matching, omission behavior), though example values for message_protocol endpoints are thin.

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 ('Find agents') plus the exact filter dimensions and ranking basis ('composite score: capability match + trust + success rate'). It also explicitly distinguishes itself from sibling verify_agent, so an agent can route correctly 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 Guidelines5/5

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

Gives explicit when-to-use-the-alternative guidance: 'Use verify_agent only for an agent_id you don't have match/registry data for, or to force a fresh check before a high-value action.' It also states the at-least-one-filter constraint and that results can include unverified agents, so the agent knows when NOT to rely on this tool alone.

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