Skip to main content
Glama

agent-tools (x402 + MCP + A2A directory)

ask_services

Read-only

Ask for the best x402/MCP services for an agent intent.

This is the high-level discovery tool: it retrieves candidates from the
directory, asks the configured backend LLM to rank only those candidates,
and returns service cards for the selected recommendations. If the LLM is
unavailable, it falls back to the directory ranker.

Args:
    intent: Natural-language job the agent wants to accomplish.
    top_k: Max recommendations to return (1-10).
    max_price_usd: Optional per-call budget cap.
    category: Optional directory category filter.
    chain: Optional payment network filter, e.g. "base" or "solana".
    require_healthy: When true, only consider services marked health=ok.
    min_confidence: Optional x402scan quality floor (0.0-1.0).
    has_mcp: When true, only consider services with MCP endpoints.
    use_llm: Set false for deterministic retrieval-only fallback.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "intent": "<intent>"
    },
    "name": "ask_services"
  }
}

Input Schema

NameRequiredDescriptionDefault
chainNoOptional payment network filter, e.g. "base" or "solana".
top_kNoMax recommendations to return (1-10).
intentYesNatural-language job the agent wants to accomplish.
has_mcpNoWhen true, only consider services with MCP endpoints.
use_llmNoSet false for deterministic retrieval-only fallback.
categoryNoOptional directory category filter.
max_price_usdNoOptional per-call budget cap.
min_confidenceNoOptional x402scan quality floor (0.0-1.0).
require_healthyNoWhen true, only consider services marked health=ok.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • addedInput schema / properties / category / description
      Added value: +"Optional directory category filter."
    • addedInput schema / properties / chain / description
      Added value: +"Optional payment network filter, e.g. \"base\" or \"solana\"."
    • addedInput schema / properties / has_mcp / description
      Added value: +"When true, only consider services with MCP endpoints."
    • addedInput schema / properties / intent / description
      Added value: +"Natural-language job the agent wants to accomplish."
    • addedInput schema / properties / max_price_usd / description
      Added value: +"Optional per-call budget cap."
    • addedInput schema / properties / min_confidence / description
      Added value: +"Optional x402scan quality floor (0.0-1.0)."
    • addedInput schema / properties / require_healthy / description
      Added value: +"When true, only consider services marked health=ok."
    • addedInput schema / properties / top_k / description
      Added value: +"Max recommendations to return (1-10)."
    • addedInput schema / properties / use_llm / description
      Added value: +"Set false for deterministic retrieval-only fallback."
  2. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations only declare readOnlyHint and openWorldHint=false, so the description carries the real disclosure burden and does it well: it explains the two-stage pipeline (directory retrieval, then LLM ranking of only those candidates), and that an LLM-unavailable path degrades to the deterministic directory ranker. The one gap is that non-determinism, latency, and cost of the LLM ranking step per call are not spelled out for the caller.

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

Conciseness3/5

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

The opening paragraph is dense, front-loaded and earns its place, but the nine-line Args list duplicates the input schema word for word and inflates the definition without adding information. Trimming that block would leave a tighter, more useful description.

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

Completeness4/5

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

With an output schema present, the description need not explain return values, and it still usefully notes that it returns service cards for the selected recommendations. Combined with the pipeline and fallback behavior, an agent has enough to call this correctly; only the interaction between the several optional filters is left unstated.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter is already documented in the input schema, and the Args block restates those same descriptions almost verbatim (e.g. "Optional payment network filter, e.g. \"base\" or \"solana\""). No additional semantics such as interaction between filters, tie-breaking, or what happens when filters exclude everything are added, so the baseline of 3 applies.

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

Purpose4/5

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

The first sentence names a specific verb and resource ("Ask for the best x402/MCP services for an agent intent") and the second labels the tool's role ("the high-level discovery tool"), so an agent can place it among siblings like search_mcp_servers or list_categories. It stops short of a 5 because it never names an alternative tool directly; the differentiation is positional rather than explicit.

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?

"This is the high-level discovery tool" plus the note that it falls back to the directory ranker if the LLM is unavailable gives clear context on when this is the right entry point versus raw retrieval. It does not state outright which sibling to use for plain keyword lookup, so it is clear context without exclusions.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.