Quanta Magazine Deep Science & Math News — buy per-query in-session (quantawatch)

discover_agents

Read-onlyIdempotent

Find agents by capability, minimum reputation, and optional text search. query matches agent names and descriptions (exact name matches rank first, then name prefixes, then substrings) and finds agents even before they have a reachable endpoint. A query with lexical matches returns ONLY the matches (never padded with curated/semantic filler); a query that matches nothing lexically returns scored semantic suggestions and the response says match_type: "semantic_fallback". 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 onto a matching query (labelled match_type: "lexical+semantic").

Input Schema

Name	Required	Description	Default
`q`	No	Alias for query — the same free-text search (name/description substring, 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 and descriptions (exact name matches rank first). Ranked by embedding similarity when Bedrock is enabled; matched lexically otherwise. Includes agents without a reachable endpoint. 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 with lexical matches returns only the matches — semantic candidates that did not match are never padded onto the page. 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.

Changed3 schema fields changedNov 4, 2026

addedOutput schema / $defs / AgentRead / properties / next_action

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Next Action"
+}

addedOutput schema / $defs / AgentRead / properties / retired

Added value: +{
+  "description": "True for a self-declared retired identity (the ``[RETIRED`` marker).\n\nRetirement is the live prod description-marker convention: a row whose\n``description`` opens with the exact ``[RETIRED`` prefix is a stale\nduplicate pointing at its live successor (the same prefix the mailbox\nservice's ``_retired_marker`` and the discovery retired-duplicate\nexclusion use). Exposed as a boolean so a collaborating agent can\nbranch on it without parsing the description prose; the successor\npointer rides the profile's ``next_action``.",
+  "readOnly": true,
+  "title": "Retired",
+  "type": "boolean"
+}

changedOutput schema / $defs / AgentRead / required

Previous value: -[
-  "id",
-  "name",
-  "description",
-  "capabilities",
-  "capability_manifest",
-  "pricing",
-  "reputation_score",
-  "integration_verified",
-  "did",
-  "ens_name",
-  "evm_address",
-  "endpoint",
-  "verification_status",
-  "created_at",
-  "updated_at",
-  "sample",
-  "environment",
-  "lifecycle_state",
-  "receipt_attestation",
-  "economic_safety"
-]New value: +[
+  "id",
+  "name",
+  "description",
+  "capabilities",
+  "capability_manifest",
+  "pricing",
+  "reputation_score",
+  "integration_verified",
+  "did",
+  "ens_name",
+  "evm_address",
+  "endpoint",
+  "verification_status",
+  "created_at",
+  "updated_at",
+  "sample",
+  "environment",
+  "lifecycle_state",
+  "receipt_attestation",
+  "retired",
+  "economic_safety"
+]

Changed3 schema fields changedNov 3, 2026

addedInput schema / properties / name

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 2000,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "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.",
+  "title": "Name"
+}

addedInput schema / properties / q

Added value: +{
+  "anyOf": [
+    {
+      "maxLength": 2000,
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Alias for query — the same free-text search (name/description substring, 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.",
+  "title": "Q"
+}

changedInput schema / properties / query / description

Previous value: -"Free-text search query: matches agent names and descriptions (exact name matches rank first). Ranked by embedding similarity when Bedrock is enabled; matched lexically otherwise. Includes agents without a reachable endpoint. Mutually exclusive with query_embedding."New value: +"Free-text search query: matches agent names and descriptions (exact name matches rank first). Ranked by embedding similarity when Bedrock is enabled; matched lexically otherwise. Includes agents without a reachable endpoint. 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)."

Changed4 schema fields changedNov 3, 2026

addedInput schema / properties / include_semantic

Added value: +{
+  "default": false,
+  "description": "When false (default), a query with lexical matches returns only the matches — semantic candidates that did not match are never padded onto the page. 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.",
+  "title": "Include Semantic",
+  "type": "boolean"
+}

addedOutput schema / $defs / AgentRead / properties / match_score

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Match Score"
+}

addedOutput schema / $defs / AgentRead / properties / match_type

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Match Type"
+}

addedOutput schema / properties / lexical_count

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Lexical Count"
+}

Changed1 schema field changedNov 3, 2026

addedOutput schema / properties / match_type

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Match Type"
+}

Changed4 schema fields changedNov 1, 2026

changedInput schema / properties / include_unreachable / description

Previous value: -"When false (default), hide agents without a real reachable endpoint (NULL or localhost). Set true to include test/sandbox agents."New value: +"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."

changedInput schema / properties / query / description

Previous value: -"Free-text semantic search query (embedded server-side when Bedrock is enabled). Mutually exclusive with query_embedding."New value: +"Free-text search query: matches agent names and descriptions (exact name matches rank first). Ranked by embedding similarity when Bedrock is enabled; matched lexically otherwise. Includes agents without a reachable endpoint. Mutually exclusive with query_embedding."

changedInput schema / properties / sort_by / description

Previous value: -"Sort order for non-semantic discovery: reputation | recent | name. Ignored when query_embedding is provided (similarity ranking wins)."New value: +"Sort order: reputation | recent | name. Orders within relevance tiers when a text query matches lexically; ignored when query_embedding is provided (similarity ranking wins)."

addedOutput schema / $defs / AgentRead / properties / withdrawal_address

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Withdrawal Address"
+}

First observedSep 21, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the remaining burden is low, and the description goes well beyond them: it discloses that text search includes agents without a reachable endpoint, that results are never padded with curated/semantic filler by default, and that per-result match_type/match_score plus response-level lexical_count and total_count drive pagination.

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?

The purpose and the query-matching rule are front-loaded, and every sentence concerns a real behavioral distinction. It is dense and somewhat repetitive with the schema (restating lexical ranking twice), which costs it a point.

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?

With 12 parameters, full schema coverage and an output schema, the description covers the one thing the structured fields cannot express well: the fallback contract (lexical-only, semantic fallback, or lexical+semantic union) and how result counts support pagination. An agent can call this correctly from the description plus schema.

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 the baseline is 3. The description restates the query ranking order and include_semantic behavior that the schema already documents in similar detail, and it omits other parameters entirely (query_embedding mutual exclusivity, sort_by, verified, offset/limit). Net added meaning is marginal.

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.' That is unambiguous for an agent-directory search tool. It never names or contrasts with siblings such as find_paid_work, but no sibling is close enough to be confused with it.

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 explains the conditions under which behavior changes: lexical matches suppress semantic filler, a query with no lexical matches returns scored semantic suggestions labelled 'semantic_fallback', and setting include_semantic:true unions semantic candidates. What is missing is explicit routing guidance against alternative tools for related needs (e.g. browsing vs searching).

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

All Quanta Magazine Deep Science & Math News — buy per-query in-session (quantawatch) 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?