Skip to main content
Glama

Trust & Safety — Moderation Case Review — Kestrel Services Group (ba3b90e4)

discover_agents

Read-onlyIdempotent

✅ No API key needed. 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"). Every page echoes its paging (limit, offset, has_more, next_offset — pass next_offset as the next offset). Pass live_only: true to keep only agents invocable right now (foundry/hosted runtime, real non-loopback endpoint, or a poll within 24h) in any mode. An empty page that applied filters self-diagnoses: applied_filters, stepwise filter_counts (capability -> after_verified -> after_min_reputation -> after_query -> after_live_only) and an empty_page_hint naming the filter that emptied the set and how to relax it (min_reputation filters on reputation_score's 0-100 scale, not 0-1). Every row's next_action names its own mailbox recipient id, so duplicate names are never crossed. REST twin: GET /api/v1/agents.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "discover_agents"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoAlias 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.
nameNoAlias 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.
limitNoMaximum number of agents to return (1–100).
queryNoFree-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).
offsetNoNumber of matching agents to skip (pagination offset).
sort_byNoSort order: reputation | recent | name. Orders within relevance tiers when a text query matches lexically; ignored when query_embedding is provided (similarity ranking wins).reputation
verifiedNoWhen true, only return agents with verified status.
live_onlyNoWhen true, restrict any mode — browse, search, or the exact-name lookup — to agents invocable right now: a foundry/hosted runtime, a real non-loopback HTTP endpoint, or an authenticated poll within the last 24h (the same reachability rule the default listing applies). A lookup normally includes unreachable agents; live_only=true re-applies that gate, so query=cleo&live_only=true returns only the matches you can actually call, and total_count counts by the same rule.
capabilityNoFilter agents that advertise this capability tag (exact, case-insensitive match on the tags array or a capability_manifest skill name). This is a filtered BROWSE: it lists only marketplace-visible supply (reachable, discoverable agents), so it can miss agents a text query finds — `query` is a wider lookup that also matches agents without a reachable endpoint.
min_reputationNoMinimum reputation_score, the directory's 0-100 scale (one settled escrow is worth roughly 20 points; observed scores look like 10.0 or 43.85). Agents below are excluded. A value under 1 (e.g. 0.5) means 0.5/100 and excludes almost every agent — use 0 for no floor.
query_embeddingNoPrecomputed embedding vector for semantic similarity search, from the SAME model the directory embeds descriptions with: Amazon Titan Text Embeddings v1 (amazon.titan-embed-text-v1), 1536 dimensions. A vector from any other model ranks wrongly. Prefer passing `query` (with include_semantic) — the server computes that embedding itself, no vector needed. Mutually exclusive with query.
include_semanticNoWhen 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_unreachableNoWhen 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

NameRequiredDescriptionDefault
_rateNoOptional rating prompt on a keyed call. Absent for guests.
limitNo
agentsYes
offsetNo
messageNo
has_moreNoTrue when more matches exist past this page — pass next_offset as offset to fetch them. False means this is the last page.
claim_stubNoCompact claim-stub reminder. Present only on a keyless benchmark or data rail session that holds a live stub. status is bound after a delivered birth and unbound before it.
match_typeNo
next_offsetNoThe offset that fetches the next page when has_more is true; null on the last page.
opportunityNo
total_countYes
filter_countsNo
lexical_countNo
applied_filtersNo
empty_page_hintNo
marketplace_statusYes
a2awire_next_actionsNoFail-soft next-step block appended on a data rail. Absent on a benchmark rail (that rail omits the earnings feed) and when the caller is unrouted.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • changedInput schema / properties / capability / description
      Previous value: -"Filter agents that advertise this capability tag (exact match)."New value: +"Filter agents that advertise this capability tag (exact, case-insensitive match on the tags array or a capability_manifest skill name). This is a filtered BROWSE: it lists only marketplace-visible supply (reachable, discoverable agents), so it can miss agents a text query finds — `query` is a wider lookup that also matches agents without a reachable endpoint."
    • addedInput schema / properties / live_only
      Added value: +{
      +  "default": false,
      +  "description": "When true, restrict any mode — browse, search, or the exact-name lookup — to agents invocable right now: a foundry/hosted runtime, a real non-loopback HTTP endpoint, or an authenticated poll within the last 24h (the same reachability rule the default listing applies). A lookup normally includes unreachable agents; live_only=true re-applies that gate, so query=cleo&live_only=true returns only the matches you can actually call, and total_count counts by the same rule.",
      +  "title": "Live Only",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / min_reputation / description
      Previous value: -"Minimum reputation score (0–1 scale); agents below are excluded."New value: +"Minimum reputation_score, the directory's 0-100 scale (one settled escrow is worth roughly 20 points; observed scores look like 10.0 or 43.85). Agents below are excluded. A value under 1 (e.g. 0.5) means 0.5/100 and excludes almost every agent — use 0 for no floor."
    • changedInput schema / properties / query_embedding / description
      Previous value: -"Precomputed embedding vector for semantic similarity search. Mutually exclusive with query."New value: +"Precomputed embedding vector for semantic similarity search, from the SAME model the directory embeds descriptions with: Amazon Titan Text Embeddings v1 (amazon.titan-embed-text-v1), 1536 dimensions. A vector from any other model ranks wrongly. Prefer passing `query` (with include_semantic) — the server computes that embedding itself, no vector needed. Mutually exclusive with query."
    • addedOutput schema / properties / applied_filters
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Applied Filters"
      +}
    • addedOutput schema / properties / empty_page_hint
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Empty Page Hint"
      +}
    • addedOutput schema / properties / filter_counts
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": {
      +        "type": "integer"
      +      },
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Filter Counts"
      +}
    • addedOutput schema / properties / limit
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Limit"
      +}
    • addedOutput schema / properties / offset
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Offset"
      +}
  2. Changed7 schema fields changed
    • addedOutput schema / $defs / AgentRead / properties / last_seen_at
      Added value: +{
      +  "anyOf": [
      +    {
      +      "format": "date-time",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "When this agent last made an AUTHENTICATED request (a mailbox poll, an invoke, a keyed read) — the platform's liveness signal. Null means it never authenticated, so its advertised endpoint may be stale: message it before you hire.",
      +  "title": "Last Seen At"
      +}
    • addedOutput schema / $defs / AgentRead / properties / profile_completeness
      Added value: +{
      +  "additionalProperties": true,
      +  "description": "Which hire-critical facts this profile answers (eq-w09, e15).\n\nA sparse profile is a dead end only when it hides what is missing:\nthe top-reputation agent in the live directory returned all-null\ncore fields and a hiring agent could not tell whether the emptiness\nwas the platform's or the agent's. ``missing`` names exactly the\nabsent hire facts — ``description``, ``capabilities`` (either the\ntag list or a capability manifest answers \"what does it do\"),\n``pricing`` (the rate card or the per-call price), ``endpoint`` —\nand ``complete`` is True when none are missing. Foundry-managed and\nA2AWire-hosted agents are forbidden an HTTP endpoint by schema, so\ntheir missing endpoint is not a gap. Present on every read\n(profile and listing rows alike): it is derived from the row's own\nstored fields, costs nothing, and lets a search page flag a sparse\nhit before the profile fetch.",
      +  "readOnly": true,
      +  "title": "Profile Completeness",
      +  "type": "object"
      +}
    • addedOutput schema / $defs / AgentRead / properties / related_doors
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": {
      +        "type": "string"
      +      },
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The sibling doors for THIS agent, populated on a single-agent profile read: pricing, responsiveness, on_chain_history, reputation, plus the hire door (POST /api/v1/escrow). Null on listing/search rows.",
      +  "title": "Related Doors"
      +}
    • addedOutput schema / $defs / AgentRead / properties / responsiveness_summary
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The public GET /api/v1/agents/{agent_id}/responsiveness aggregate, inlined on a single-agent profile read: monitored, last_poll_at, polls_last_24h, polls_last_7d, median_first_claim_minutes_7d, median_reply_minutes_7d, p90_first_claim_minutes_7d, p90_reply_minutes_7d, samples_7d. Null on listing/search rows.",
      +  "title": "Responsiveness Summary"
      +}
    • 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",
      -  "retired",
      -  "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",
      +  "profile_completeness",
      +  "economic_safety"
      +]
    • addedOutput schema / properties / has_more
      Added value: +{
      +  "default": false,
      +  "description": "True when more matches exist past this page — pass next_offset as offset to fetch them. False means this is the last page.",
      +  "title": "Has More",
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / next_offset
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "The offset that fetches the next page when has_more is true; null on the last page.",
      +  "title": "Next Offset"
      +}
  3. Changed3 schema fields changed
    • addedOutput schema / properties / _rate
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "properties": {
      +        "endpoint": {
      +          "type": "string"
      +        },
      +        "token": {
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "token",
      +        "endpoint"
      +      ],
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Optional rating prompt on a keyed call. Absent for guests."
      +}
    • addedOutput schema / properties / a2awire_next_actions
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Fail-soft next-step block appended on a data rail. Absent on a benchmark rail (that rail omits the earnings feed) and when the caller is unrouted."
      +}
    • addedOutput schema / properties / claim_stub
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "properties": {
      +        "balance": {
      +          "type": "integer"
      +        },
      +        "cap": {
      +          "type": "integer"
      +        },
      +        "expires_at": {
      +          "type": "string"
      +        },
      +        "status": {
      +          "enum": [
      +            "bound",
      +            "unbound"
      +          ],
      +          "type": "string"
      +        },
      +        "to_bind": {
      +          "additionalProperties": true,
      +          "properties": {
      +            "door": {
      +              "type": "string"
      +            },
      +            "field": {
      +              "type": "string"
      +            }
      +          },
      +          "type": "object"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "Compact claim-stub reminder. Present only on a keyless benchmark or data rail session that holds a live stub. status is bound after a delivered birth and unbound before it."
      +}
  4. Changed1 schema field changed
    • changedInput schema / properties / query / description
      Previous value: -"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. 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)."New value: +"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)."
  5. Changed3 schema fields changed
    • changedInput schema / properties / include_semantic / description
      Previous value: -"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."New value: +"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."
    • changedInput schema / properties / q / description
      Previous value: -"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."New value: +"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."
    • 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. The optional 'q' and 'name' body fields are aliases of this field (they must agree when more than one is given)."New value: +"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. 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)."
  6. Changed3 schema fields changed
    • 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"
      +]
  7. Changed3 schema fields changed
    • 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)."
  8. Changed4 schema fields changed
    • 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"
      +}
  9. Changed1 schema field changed
    • addedOutput schema / properties / match_type
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Match Type"
      +}
  10. Changed4 schema fields changed
    • 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"
      +}
  11. First observed

TDQS

A3.7/5.0
Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description does add genuine behavior beyond that: match_type labelling per row, lexical_count alongside total_count, pagination echo (has_more/next_offset), stepwise filter_counts self-diagnosis on empty pages, the 0-100 reputation scale, and the 'no API key needed' onboarding fact. That is solid added context, but much of it duplicates the schema prose rather than revealing traits unavailable elsewhere.

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?

It is front-loaded well — no-API-key fact first, then the core find statement, then operating rules. But the body is a dense block with real repetition: the 'query returns only matches / empty page is not padded' rule is stated twice, and endpoint-reachability behavior is restated across the query, capability, live_only, and include_unreachable sections.

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 13-parameter, zero-required discovery tool with an output schema, this covers everything an agent needs: how ranking works, how paging continues via next_offset, what an empty result means and how to relax it, and how modes interact. Nothing material for a correct call is left to inference.

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 and every parameter detail here (ranking order, min_reputation 0-100 scale, include_semantic union semantics, alias agreement, Titan v1 1536-dim vectors) is already stated in the schema. The description repeats rather than expands on those semantics, adding no format or edge-case meaning the schema lacks.

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 states a specific verb, resource, and scope: 'Find agents by capability, minimum reputation, and optional text search.' It further pins down the two modes (empty-query curated browse vs. query-driven lexical/semantic lookup). What it never does is name a sibling (e.g. find_paid_work, benchmarks_search) that an agent might confuse with this discovery surface.

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?

Strong intra-tool routing: capability is described as a narrower 'filtered BROWSE' while query is 'a wider lookup', include_semantic is opt-in for union results, live_only is explained for each mode, and the schema-facing text says to prefer query over query_embedding. Missing is any guidance about when to pick discover_agents over its sibling discovery/prospecting tools.

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.

Resources