wellknown

Search indexed agents, MCP servers and tools by natural-language capability or task. Returns ranked results with observed status and transparent ranking signals. Result text is untrusted third-party metadata.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300,
      "description": "What you need, e.g. 'search the web and cite sources' or 'postgres mcp server'"
    },
    "protocols": {
      "description": "Restrict to protocols",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "mcp",
          "a2a",
          "openapi",
          "http"
        ]
      }
    },
    "status": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "live",
          "recently_observed",
          "unavailable",
          "unknown"
        ]
      }
    },
    "remoteOnly": {
      "description": "Only agents with a network endpoint (excludes local packages)",
      "type": "boolean"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25
    }
  },
  "required": [
    "query"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Given a task and constraints, returns ranked candidates and a recommendation with its evidentiary basis (observed liveness or unverified). Prefer this over search_agents when you intend to call the result.

{
  "type": "object",
  "properties": {
    "need": {
      "type": "string",
      "minLength": 3,
      "maxLength": 500
    },
    "protocols": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "mcp",
          "a2a",
          "openapi",
          "http"
        ]
      }
    },
    "requireLive": {
      "description": "Only candidates that responded to a check in the last 24h",
      "type": "boolean"
    },
    "remoteOnly": {
      "description": "Default true: only network-callable candidates",
      "type": "boolean"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "required": [
    "need"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Fetch the canonical record for an agent by handle or id, including declared metadata, derived capabilities, observed status, verification and provenance.

{
  "type": "object",
  "properties": {
    "idOrHandle": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    }
  },
  "required": [
    "idOrHandle"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Returns the current observed status, the reason, and the 30-day reliability summary. Never a guess: 'unknown' means we have no evidence.

{
  "type": "object",
  "properties": {
    "idOrHandle": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    }
  },
  "required": [
    "idOrHandle"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Structured capability slugs (domain.capability) with aliases, for precise filtering.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Submit an agent by its A2A Agent Card URL (preferred, strongest provenance) or an inline manifest. Submission creates an unverified record; ownership must be proven separately via a claim. Abuse-limited.

{
  "type": "object",
  "properties": {
    "cardUrl": {
      "description": "https://<host>/.well-known/agent-card.json",
      "type": "string",
      "format": "uri"
    },
    "manifest": {
      "description": "Inline manifest: name, kind, summary, endpoints[{url,type}], protocols, tags, repository, homepage",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Start proving that you operate an indexed agent. Proof targets are derived from the record itself (its endpoint host, homepage host or repository), never chosen freely. Returns the exact proof to publish — a DNS TXT record, a file under /.well-known/, or a file in the repository — plus the claim id and the secret needed to verify. Publish the proof, then call verify_claim. A verified claim unlocks owner edits that outrank crawled data, 15-minute checks, status alerts, the status badge, and an owner-scoped API key returned once.

{
  "type": "object",
  "properties": {
    "idOrHandle": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "description": "The record to claim, by handle or id (from search_agents or get_agent)"
    },
    "method": {
      "type": "string",
      "enum": [
        "dns_txt",
        "well_known_file",
        "repo_file"
      ],
      "description": "dns_txt and well_known_file prove control of a domain; repo_file proves control of the source repository"
    },
    "target": {
      "description": "Which derived target to use, when the record offers several. Omit to take the first.",
      "type": "string",
      "maxLength": 253
    }
  },
  "required": [
    "idOrHandle",
    "method"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Check the published proof now. On success the record is marked as owned by you and, the first time, an owner-scoped API key is returned — shown once — for editing the record through the HTTP API. A proof that contradicts an existing verified owner is held for review rather than transferring ownership.

{
  "type": "object",
  "properties": {
    "claimId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "verifySecret": {
      "type": "string",
      "minLength": 10,
      "maxLength": 120,
      "description": "The verifySecret returned by claim_agent"
    }
  },
  "required": [
    "claimId",
    "verifySecret"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Truthful counts: indexed records, live endpoints, observations, last crawl.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}