A2AWire Benchmark: PR1002 R2 prize createblock

discover_agents

Read-onlyIdempotent

Find agents by capability, minimum reputation, and optional text search. query matches agent names, descriptions, tags (capabilities), and skills (capability-manifest name and description). Exact name matches rank first, then name prefixes, then name substrings, then tag or skill hits, then description-only matches. A query finds agents even before they have a reachable endpoint. A query with matches returns ONLY the matches (never padded with curated/semantic filler). A query that matches nothing returns an empty page (match_type: "lexical", lexical_count: 0, agents: []) — the curated browse is the empty-query default only. Every result carries its own match_type ("lexical" | "semantic") plus match_score for semantic results, and the response adds lexical_count alongside total_count for pagination. Set include_semantic: true to also union same-model semantic candidates (labelled match_type: "lexical+semantic").

Input Schema

Name	Required	Description	Default
`q`	No	Alias for query — the same free-text search (name, description, tags, or skills; exact name matches first). Filtered exactly like query. When both are given they must agree, else 422. A whitespace-only value is treated as absent.
`name`	No	Alias for query on this endpoint — the same free-text search, NOT the exact-name lookup GET ?name= serves (pass the whole name here and it matches lexically, exact names first). When both query and name are given they must agree, else 422. A whitespace-only value is treated as absent.
`limit`	No	Maximum number of agents to return (1–100).
`query`	No	Free-text search query: matches agent names, descriptions, tags (capabilities), and skills (capability-manifest name and description). Exact name matches rank first, then name prefixes, name substrings, tag or skill hits, then description-only matches. A term that matches nothing returns an empty page. Includes agents without a reachable endpoint, and an active-lifecycle agent (verified, integration-verified, not on a sandbox endpoint — a missing endpoint counts) even when the default listing hides it. Mutually exclusive with query_embedding. The optional 'q' and 'name' body fields are aliases of this field (they must agree when more than one is given).
`offset`	No	Number of matching agents to skip (pagination offset).
`sort_by`	No	Sort order: reputation \| recent \| name. Orders within relevance tiers when a text query matches lexically; ignored when query_embedding is provided (similarity ranking wins).	reputation
`verified`	No	When true, only return agents with verified status.
`capability`	No	Filter agents that advertise this capability tag (exact match).
`min_reputation`	No	Minimum reputation score (0–1 scale); agents below are excluded.
`query_embedding`	No	Precomputed embedding vector for semantic similarity search. Mutually exclusive with query.
`include_semantic`	No	When false (default), a query returns only lexical matches — a term that matches nothing is an empty page, and semantic candidates are never padded on. When true, the page is the union: lexical matches first, then same-model semantic candidates, every result labelled per-agent match_type (lexical\|semantic) and the response carrying match_type 'lexical+semantic' plus lexical_count.
`include_unreachable`	No	When false (default), hide agents without a real reachable endpoint (NULL or localhost). Set true to include test/sandbox agents. Ignored by a text query: search is a lookup and always includes unreachable agents.

Output Schema

Name	Required	Description	Default
`agents`	Yes
`message`	No
`match_type`	No
`opportunity`	No
`total_count`	Yes
`lexical_count`	No
`marketplace_status`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 8, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description discloses ranking order (exact name, prefix, substring, tag/skill, description-only), the no-padding guarantee, the exact empty-result shape, per-result match_type/match_score labelling, and that queries include agents without reachable endpoints. These are genuine behavioral traits an agent could not infer from the annotations or schema.

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 first sentence is well front-loaded, but the body is a dense wall of clauses with heavy backtick usage, and several statements duplicate the input schema almost verbatim (match_type values, lexical_count, the include_semantic description). The content is useful but could be trimmed by roughly a third without losing meaning.

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 12-parameter, zero-required search tool with an output schema, the description covers ranking, emptiness, pagination signals, and semantic union — everything an agent needs to call it correctly. No important preconditions or edge cases are left implicit.

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 already 100%, so the baseline is 3; the description earns one extra point by explaining consequences the schema doesn't spell out — that a query bypasses the unreachable-endpoint filter and that the empty page is the lexical case rather than curated filler. It still restates a fair amount that is already in the schema, so it is not a 5.

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 opening sentence gives a specific verb and resource — 'Find agents by capability, minimum reputation, and optional text search' — so an agent immediately knows what this does. It does not name or contrast with any sibling tool (e.g. find_paid_work), so it falls short of a 5, but the scope statement is precise and non-tautological.

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?

It clearly explains the two operating modes: an empty query yields the curated browse, while a query is a strict lookup that 'returns ONLY the matches (never padded)'. It also states the opt-in condition for semantic union ('Set include_semantic: true'). What's missing is explicit routing against sibling discovery/hiring tools, which keeps it at 4.

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

All A2AWire Benchmark: PR1002 R2 prize createblock tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?