A
licenseNot graded
qualityB
maintenanceGates agent tool execution with human approval, audit trails, and replay-resistant permits, enabling safe use of tools in agent loops.
MIT
X-EGO
by com.x-ego
Server Details
Human approval for irreversible AI agent actions, bound to the exact tool call by a passkey tap
If you are the author of this connector, you can claim ownership with GitHub, an HTTP challenge, or a DNS record. Claimed connector authors can inspect health checks, view analytics, and manage their listing.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
TDQS
A4.6/5.0
Scored across 4 tools
Disambiguation4/5
Each tool has a distinct role: request the proof URL, verify bare presence (verify_proof), verify an action-bound token (verify_action), and check dedup (check_pairwise_seen_before). The verify_proof/verify_action pair is the only real overlap risk, but descriptions and explicit cross-redirecting error codes (action_binding_required) resolve it clearly.
Naming Consistency5/5
All four tools share the xego_ prefix and snake_case, with consistent verb_noun phrasing (check_..., request_..., verify_...). No mixed conventions or stylistic deviations.
Tool Count4/5
Four tools map cleanly onto the verification lifecycle (request URL, verify presence, verify action, dedup), and each earns its place. It is on the lean side but not thin given the narrow domain.
Completeness4/5
Covers the full flow from sending a human to verifying the returned token, plus sybil suppression. Minor gaps (no explicit JWKS/introspection or standalone record/revoke operation), but agents can work around these via the existing tools.
Available Tools
4 toolsxego_check_pairwise_seen_beforeCheck whether this user was seen beforeAIdempotentInspect
Checks whether a given pairwise ID has already been seen within this audience. It protects against one person acting as several different users (multiple accounts, repeat voting, and similar).
WHEN TO USE: returning-user checks and one-human-one-vote. Requires a pairwise_id previously obtained from a verify call for YOUR audience.
Only the pair (audience, pairwise_id) and the time of first occurrence are recorded. No personal data.
The ledger is PERMANENT and shared across every instance and session of the server (Postgres) — it survives restarts and new MCP sessions. record_if_new=true writes atomically (no window for a concurrent write).
Args:
audience (string): the service domain or URL. Normalized to a bare lowercase hostname — the same key the proof was issued under, so a domain and its URL form are the same audience.
pairwise_id (string): the identifier from xego_verify_proof.
record_if_new (boolean): record the user if they are new.
Returns (JSON): { "seen_before": boolean, // true = already on record "first_seen": number|null, // Unix time of first occurrence "recorded_now": boolean // true = recorded just now }
Errors (free, no sybil check performed): invalid_audience (the audience cannot be normalized to a domain), dedup_store_unavailable (temporary — retry). Neither ever means 'not seen before'.
PAID TOOL (x402): this call costs $0.01 USD in USDC per execution, unless you send a valid X-EGO pilot operator key as an 'Authorization: Bearer ' HTTP header (operator calls are free). Calling without payment returns an x402 error whose _meta["x402/error"] contains payment requirements (accepts) and step-by-step instructions how to pay and retry. Invalid input is rejected for free before any payment is taken.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| audience | Yes | The service being asked about. Domain (forum.example.com) or full URL (https://forum.example.com/...) — both are normalized to a bare lowercase hostname, exactly like the token's aud. | |
| pairwise_id | Yes | The user's pairwise identifier (from the xego_verify_proof result). | |
| record_if_new | No | If true and the user has not been seen yet, they are recorded immediately — an atomic 'is new? then mark' in one call. |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations by disclosing that the ledger is PERMANENT and shared across instances/sessions (Postgres, survives restarts), that record_if_new writes atomically with no concurrency window, that only (audience, pairwise_id) plus first-seen time is stored, and the full paid-tool x402 flow including a free operator-key bypass. It also enumerates error cases and clarifies none of them mean 'not seen before'.
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?
Well-structured and front-loaded, with purpose first, then WHEN TO USE, ledger semantics, Args, Returns, and Errors/payment. The Args and Returns sections partially restate the schema, which adds length, but the added value (normalization, atomicity, error semantics) keeps it mostly efficient.
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?
Although no output schema exists, the description inlines the JSON return shape, documents error cases with their meaning, and explains the payment model. Nothing an agent needs to call and interpret the tool correctly appears to be missing.
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?
With 100% schema coverage the schema already documents all three parameters, so the baseline is 3. The description adds meaning on top: audience is normalized to a bare lowercase hostname (same key the proof was issued under), and record_if_new's atomic 'is new? then mark' behavior is explained beyond the schema's wording.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Checks whether a given pairwise ID has already been seen within this audience') and states the concrete goal it serves (preventing one person acting as several users). It also positions the tool in the workflow by noting the pairwise_id must come from a verify call, which distinguishes it from the verify siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
An explicit 'WHEN TO USE' line names the scenarios (returning-user checks, one-human-one-vote) and the prerequisite ('Requires a pairwise_id previously obtained from a verify call for YOUR audience'). An agent knows both when to call it and what inputs must exist first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
xego_request_proof_urlGet an X-EGO verification linkARead-onlyIdempotentInspect
REQUIRES a one-time EUR 3 Planetary ID held by YOUR END USER - without it every call returns valid:false. Tell the human this BEFORE sending them to the link: if they do not have one yet, the verification page sells it in the same flow — it is not a separate signup.
Returns the URL the agent sends a human user to, so they can
prove they are human. On that page the user verifies with a
passkey (fingerprint / Face ID) and receives a short-lived signed
token (JWT). The agent then verifies it with xego_verify_proof
(no action) or xego_verify_action (with action).
ASK FIRST what is being approved, then bind it. Two ways, and the choice matters more than anything else on this tool:
call— USE THIS WHENEVER A TOOL WILL RUN. Pass the exact call { v:1, tool, target, args, policy? } you are about to execute. The human approves the call itself, field by field.action— a sentence, for approvals where nothing executes (a consent, a statement). It seals what the human READ, and a well-written sentence can hide what actually happens.
Both may be passed together: the sentence is what the human
reads, the call is what gets compared. Either one means the
token MUST be verified with xego_verify_action; with neither,
use xego_verify_proof. The returned binding field says which.
For emails: recipient and content; compose the final wording and get the user's OK before calling.
This tool performs NO verification itself — it only prepares the link. No personal data is transferred.
THE USER DOES NOT HAVE TO COPY THE TOKEN. Pass redirect_uri (or return_origin) and the page delivers the token to you after the passkey tap — the human part (fingerprint / Face ID) is unchanged. redirect_uri is the recommended channel: it is the only one that survives a user who is still buying a Planetary ID in the same pass. The returned token_delivery field tells you what to expect. With neither parameter the current behaviour stays: the token is shown on the page and the human hands it to you.
Verification requires a paid Planetary ID (one-time EUR 3, ~2 min, passkey on the user's own device — biometrics never leave it). If the user does not have one yet, the verification page offers it there. Send the user to the returned verification_url; if they come back without a token, they still need the ID — verification then fails with planetary_id_required and a registration_url.
Args:
audience (string): the domain of the service requesting verification (domain or URL — normalized to a bare hostname).
call (object, RECOMMENDED when a tool will run): the exact call { v:1, tool, target, args, policy? }. Rendered field by field on the page; the token seals it. Verify with expected_call built from YOUR OWN parsed parameters.
action (string, OPTIONAL fallback): a sentence describing the approval, for cases where nothing executes. The user sees it and the token is valid only for it — pass the same string as expected_action to xego_verify_action.
redirect_uri (string, OPTIONAL): where to navigate with the token in the fragment. Only https on x-ego.com/*.x-ego.com or http(s) on loopback; no fragment. The target must be HTML that reads location.hash — a fragment is never sent in an HTTP request.
return_origin (string, OPTIONAL): origin for postMessage into window.opener, same allowlist. Popups only.
state (string, OPTIONAL): correlation value, echoed back verbatim. [A-Za-z0-9._~-], max 256 chars.
Returns (JSON): { "verification_url": string, // link for the user "audience": string, // normalized bare hostname — pass // this exact value as // expected_audience to the verify tool "action": string, // only if one was given — pass the // same string as expected_action "token_delivery": object, // mode: redirect | post_message | // manual — how the token comes back "state": string, // only if one was given — echoed // back verbatim with the token too "instructions": string, // what to do with the link "next_step": string, // next step — follow it "if_user_has_no_planetary_id": object // status planetary_id_required: // registration_url, explanation, next_step }
Errors: invalid_audience (audience cannot be normalized), invalid_redirect_uri / invalid_return_origin (target outside the allowlist, or a redirect_uri carrying a fragment), invalid_state (outside the allowed character set or length). All are free.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| call | No | RECOMMENDED whenever a tool will actually run. The exact call the human is approving: { v: 1, tool, target, args, policy? }. The verification page renders it field by field, the human taps the passkey against THAT, and the token seals it (claim cal). The executor then verifies with xego_verify_action and expected_call built from its OWN parsed parameters — never from what another party says the call is, or it is only comparing a claim with itself. Build it from the same values you are about to execute. Decimal numbers are rejected (call_unsafe_number) — use integers in minor units or strings. | |
| state | No | OPTIONAL. An opaque correlation value that lets you recognize your own request; it is echoed back verbatim (as a state field in postMessage, as &state= in the redirect fragment). Character set [A-Za-z0-9._~-]. X-EGO neither stores nor interprets it. Recommended with return_origin, where no other binding to the request exists; with redirect_uri you can carry the binding in the target's query instead. | |
| action | No | FALLBACK binding, for approvals where nothing is executed (a statement, a consent, a message being sent). A human-readable description of what the user is approving (e.g. 'Transfer EUR 500 to account 123456789/0100'). The user SEES this exact text before the passkey tap and the token is valid ONLY for it (claim act = SHA-256 of the text). Prefer `call` when a tool will run: a sentence seals what the human READ, not what then executes. May be combined with `call` — then the sentence is what the human reads and the call is what is checked. Tokens carrying either MUST be verified with xego_verify_action, not xego_verify_proof; pass the BIT-FOR-BIT identical string as expected_action (action_mismatch on any difference). | |
| audience | Yes | The domain of the service requesting verification (e.g. 'forum.example.com'). A URL is accepted too ('https://forum.example.com/path') — it is always normalized to a bare lowercase hostname (max 253 chars). It determines who the proof will be valid for. The pairwise ID differs per audience, so services cannot track a user across each other. | |
| redirect_uri | No | OPTIONAL automatic token hand-off. An absolute URL the verification page navigates to on success, with the token in the URL FRAGMENT (#token=...). The user copies nothing. Only https on x-ego.com/*.x-ego.com or http(s) on loopback (localhost, 127.0.0.1, ::1) is allowed; any other target is rejected. Path and query are preserved — put your own correlation value there. It MUST NOT carry a fragment (that is where the token goes). NOTE: a fragment is never sent in an HTTP request — the target must serve HTML that reads it in the browser (location.hash); a bare server endpoint will not see the token. This is the ONLY channel that survives a user who buys a Planetary ID mid-flow. | |
| return_origin | No | OPTIONAL automatic token hand-off into the window that opened the verification page: postMessage({type:'xego_token', token, audience, pairwise_id, state}) at the EXACT origin (never '*'). Same allowlist as redirect_uri. Use only when you opened the page as a popup via window.open. It does not work when the user buys a Planetary ID along the way — checkout severs the link to the opener window; use redirect_uri for that case. |
TDQS
A4.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/non-destructive, but the description goes well beyond them: it discloses the paid-Planetary-ID prerequisite with the exact failure mode, that the tool performs no verification and transfers no personal data, the token delivery modes, and the specific error strings. It omits little, though the repeated EUR 3 / Planetary ID restatements dilute the signal.
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?
Front-loaded with the critical prerequisite and the call/action fork, and the remaining prose is dense rather than padded. It loses a point for genuine redundancy: the EUR 3 Planetary ID requirement and the 'page sells it in the same flow' point are stated three separate times across the description.
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?
Covers the prerequisite, the binding model, all delivery channels, the full return shape (compensating for the absent output schema), and error cases. For a 6-parameter tool with a nested object and mode-switching behavior, an agent has everything needed to call it and interpret the result.
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 100%, so the baseline is 3, but the description adds real decision-level semantics the schema cannot: the call-vs-action choice 'matters more than anything else on this tool', the fragment/HTTP-request caveat for redirect_uri, and that redirect_uri is the only channel surviving a mid-flow Planetary ID purchase. The nested `call` object semantics are explained rather than merely enumerated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States precisely what the tool produces ('Returns the URL the agent sends a human user to, so they can prove they are human') and explicitly separates itself from siblings by naming `xego_verify_proof` and `xego_verify_action` as the follow-on steps. An agent can distinguish this preparatory tool from the verification tools without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit decision rules: 'USE THIS WHENEVER A TOOL WILL RUN' for `call`, `action` as fallback for non-executing approvals, both may be combined, and which verify tool to use in each case. It also prescribes ordering ('ASK FIRST what is being approved, then bind it') and the email-specific flow. This is unusually complete routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
xego_verify_actionVerify an X-EGO proof bound to an actionAIdempotentInspect
REQUIRES a one-time EUR 3 Planetary ID held by YOUR END USER - without it every call returns valid:false. Tell the human this BEFORE sending them to the link: if they do not have one yet, the verification page sells it in the same flow — it is not a separate signup.
Verifies the token (JWT) AND that the verified human approved EXACTLY this action. On top of the Ed25519 signature, the expiry and the audience, it matches the token's act claim against the hash of expected_action.
WHEN TO USE: proving a human approved one specific action. Use the exact same action text that was shown to the human. On success, the response includes a ready-made footer — insert it verbatim into the message being sent.
Use it when an agent's action must be covered by human consent — a money transfer, an account deletion, an order confirmation. The human sees the action text on the verification page and approves exactly that with their passkey; the token is then valid ONLY for this action.
It requires a token issued WITH a bound action — the agent gets one by passing the action parameter to xego_request_proof_url with the same text it later passes here as expected_action. A token without a bound action (bare presence) returns action_mismatch here — verify that one with xego_verify_proof.
Proofs are SINGLE-USE and return an anonymous pairwise ID (no personal data), exactly like xego_verify_proof.
On success the response already carries receipt_url (https://x-ego.com/receipt?r= — a public receipt anyone can open with no tools) and READY-MADE footers: footer_en (plain text) and footer_html_en (a visual badge for HTML mail; no images, no tracking). Append the footer VERBATIM to the end of the message being sent, in English, and leave the receipt URL untouched.
Args:
token (string): the JWT from the user (issued with a bound action).
expected_audience (string, REQUIRED): pins the audience.
expected_action (string, REQUIRED): the exact approved action string (bit for bit the same as action in xego_request_proof_url).
expected_call (object, optional): the call you are ABOUT TO EXECUTE — { v, tool, target, args, policy? } — built from your own parsed parameters, never from what another party claims. REQUIRED if the token is call-bound.
mark_as_seen (boolean): record the pairwise ID as seen.
Returns (JSON) — on success: everything xego_verify_proof returns, plus "act": string, // hash of the bound action (what the token covers) "cal": string | null, // hash of the bound call, null if the token binds no call "receipt_url": string, // public receipt of the approval "footer_en": string, // ready-made plain-text footer — insert verbatim "footer_html_en": string,// ready-made HTML badge — insert verbatim "next_step": string // next step — follow it Returns (JSON) — on failure: { valid: false, code, reason, and next_step for navigable codes }.
Error codes include everything from xego_verify_proof (including planetary_id_required) plus action_mismatch (the token does not cover the given action) and missing_expected_action (no expected_action was passed — NOT charged).
Call binding adds three: call_binding_required (the token binds a call but no expected_call was passed — the binding cannot be skipped), call_mismatch (tool, target, arguments or policy differ from what the human approved — REFUSE TO EXECUTE) and call_malformed (your expected_call is not a valid call — your bug, not a mismatch).
PAID TOOL (x402): this call costs $0.15 USD in USDC per execution, unless you send a valid X-EGO pilot operator key as an 'Authorization: Bearer ' HTTP header (operator calls are free). Calling without payment returns an x402 error whose _meta["x402/error"] contains payment requirements (accepts) and step-by-step instructions how to pay and retry. Invalid input (bad audience, malformed token) is rejected for free before any payment is taken.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | The JWT the user obtained after X-EGO verification with a bound action. Three dot-separated parts. | |
| mark_as_seen | No | If true and the token is valid, the pairwise ID is PERMANENTLY recorded as seen for that audience (see xego_verify_proof). | |
| expected_call | No | The call you are ABOUT TO EXECUTE, built from YOUR OWN parsed parameters — never from what another party claims the call is. If the token is call-bound, this is REQUIRED and must match exactly; tool, target, arguments or policy differing gives call_mismatch, and you must refuse to execute. Decimal numbers are rejected: use integers in minor units (cents) or strings. | |
| expected_action | No | REQUIRED. The exact action string the user approved — the same one passed to xego_request_proof_url as action, bit for bit (leading and trailing whitespace aside). The token must have been issued with this action; a different one gives action_mismatch. This guards against swapping the approved action (e.g. a EUR 500 transfer turning into EUR 5000). | |
| expected_audience | Yes | REQUIRED. Your own service's domain the token must have been issued for. Normalized to a bare lowercase hostname exactly like in xego_verify_proof. |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorld=true) only sketch the safety profile; the description goes far beyond them. It discloses the EUR 3 Planetary ID prerequisite, single-use proofs, anonymous pairwise ID, the $0.15 USDC x402 cost plus the free operator-key path, that invalid input is rejected for free before payment, the REFUSE-TO-EXECUTE requirement on call_mismatch, and a full error-code taxonomy.
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 critical prerequisite (Planetary ID, before payment) is front-loaded, and the long form is largely justified by the tool's complexity. There is some redundancy — the ready-made footer and receipt_url are described in both the usage and returns sections — so a few sentences are not strictly additive.
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 paid, token-verifying tool with no output schema, the description covers prerequisites, payment/retry behavior, success return fields (act, cal, receipt_url, footers, next_step), failure shape, and the full error-code list including call-binding codes. Nothing an agent needs to invoke it correctly is missing.
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 100%, so 3 is the floor, but the description adds workflow semantics the schema cannot: the token is obtained by passing the same action text to xego_request_proof_url and must be re-passed here bit-for-bit, and expected_call must be built from the agent's own parsed parameters. It adds integration meaning beyond the field-level descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise compound purpose: it verifies the JWT AND that the human approved EXACTLY this action, matching the token's act claim against the expected_action hash. It explicitly distinguishes itself from the sibling xego_verify_proof (bare presence) and reference the request-side tool xego_request_proof_url, so an agent can route between them without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit WHEN TO USE with concrete scenarios (money transfer, account deletion, order confirmation) and the conditioning rule: tokens issued with a bound action go here, bare-presence tokens go to xego_verify_proof and return action_mismatch here. It also states the prerequisite (action-bound token) and which sibling produces it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
xego_verify_proofVerify an X-EGO proof (JWT) — human presenceAIdempotentInspect
REQUIRES a one-time EUR 3 Planetary ID held by YOUR END USER - without it every call returns valid:false. Tell the human this BEFORE sending them to the link: if they do not have one yet, the verification page sells it in the same flow — it is not a separate signup.
Verifies the token (JWT) the user brought back after X-EGO verification. Cryptographically checks the Ed25519 signature against the X-EGO public keys, the expiry and the audience.
WHEN TO USE: bare presence only. If the token carries an action (act claim), this tool refuses with action_binding_required — use xego_verify_action instead.
This verifies ONLY bare human presence. If you need proof that the human approved a SPECIFIC action, use xego_verify_action. A token issued with a bound action (via xego_request_proof_url with the action parameter) fails here with action_binding_required — the binding cannot be confirmed by this cheaper tool.
A valid result means: there is a verified human on the other end who holds the passkey. The token is short-lived — once it expires the user must verify again.
Proofs are SINGLE-USE: each token verifies exactly once. A second attempt on the same token returns token_replayed.
Returns an anonymous 'pairwise' identifier — different for every audience. It carries no name and no personal data.
Args:
token (string): the JWT from the user.
expected_audience (string, REQUIRED): pins the audience (domain or URL — normalized to a bare hostname).
mark_as_seen (boolean): record the pairwise ID as seen.
Returns (JSON) — on success: { "valid": true, "pairwise_id": string, // anonymous ID, stable per (user, audience) "audience": string, "expires_at": number, // Unix time the token expires "human_verified": true, "xego_verified": true, // always true — uncovered tokens never reach here "rarity": string | null, // rarity of the backing ID (low entropy) "marked_seen": boolean, // only with mark_as_seen=true: whether // the permanent ledger write succeeded "next_step": string // next step — follow it } Returns (JSON) — on failure: { "valid": false, "code": string, // machine-readable error code "reason": string, // human-readable description "next_step": string // for navigable codes: what to do now }
Error codes include: invalid_audience, malformed_token, unsupported_algorithm, unknown_key (with a kid field), bad_signature, expired, wrong_issuer, wrong_audience, action_binding_required (the token is bound to an action → use xego_verify_action), missing_claims, jwks_unavailable, token_replayed, planetary_id_required (the signature is valid but the human behind the token holds no paid Planetary ID — X-EGO does not issue uncovered proofs; send the user to registration_url and repeat the whole flow).
PAID TOOL (x402): this call costs $0.05 USD in USDC per execution, unless you send a valid X-EGO pilot operator key as an 'Authorization: Bearer ' HTTP header (operator calls are free). Calling without payment returns an x402 error whose _meta["x402/error"] contains payment requirements (accepts) and step-by-step instructions how to pay and retry. Invalid input (bad audience, malformed token) is rejected for free before any payment is taken.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| token | Yes | The JWT the user obtained after X-EGO verification. Three dot-separated parts. | |
| mark_as_seen | No | If true and the token is valid, the pairwise ID is PERMANENTLY recorded as seen for that audience (Postgres ledger — survives restarts and new sessions). Useful when you want to guard against repeat use right away (see xego_check_pairwise_seen_before). The write result is in the marked_seen field. | |
| expected_audience | Yes | REQUIRED. Your own service's domain the token must have been issued for. Domain or URL — normalized to a bare lowercase hostname exactly like audience in xego_request_proof_url. A token issued for a different audience is rejected (wrong_audience). This prevents token reuse across services and preserves pairwise isolation. |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes far beyond the annotations: discloses the $0.05 USDC x402 payment requirement plus the free operator-key path, the single-use/token_replayed behavior, short token lifetime, pairwise anonymity, the requirement of a paid Planetary ID, and the full machine-readable error-code surface. The readOnlyHint=false / destructiveHint=false pair is consistent with the disclosed optional ledger write.
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?
Headed sections (WHEN TO USE, Args, Returns, Error codes, PAID TOOL) make it scannable and the highest-stakes constraint — the paid ID requirement — is front-loaded. However, the bare-presence vs. action-binding rule is stated twice at length, and the Arg list duplicates the schema.
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?
No output schema exists, and the description fully compensates by documenting both success and failure response shapes field-by-field and enumerating the failure codes with their recovery actions. Nothing an agent needs to interpret a result or handle a rejection is missing.
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% and the schema itself already explains token format, audience normalization, and mark_as_seen's Postgres ledger effect and marked_seen result. The Args block in the description largely restates that, adding only that the token is "from the user," so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource — cryptographically verifying an X-EGO JWT (Ed25519 signature, expiry, audience) — and sharply distinguishes itself from the sibling xego_verify_action by scope (bare presence vs. action-bound). An agent can route correctly without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit WHEN TO USE section states the tool handles bare presence only, and names the exact alternative and the exact failure signal that selects it ("action_binding_required — use xego_verify_action instead"). Preconditions (EUR 3 Planetary ID held by the end user, told to the human before the link) are stated up front.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
- First observed
xego_check_pairwise_seen_before - First observed
xego_request_proof_url - First observed
xego_verify_action - First observed
xego_verify_proof
Related MCP Connectors
Human-in-the-loop approval for agent actions, with verifiable action-bound receipts.
- mcpOAuthcom.decionis
Authorize consequential AI agent actions before execution
Preventive human-approval write-gate for AI agents: writes commit only after a human approves.
Runtime permission, approval, and audit layer for AI agent tool execution.
Related MCP Servers
raposa-mcpofficial
AlicenseAqualityBmaintenanceHuman approval for AI agents: request_human_approval pauses a high-stakes action until a named person approves or rejects (console, email, Telegram, Slack); silence is not consent. Every decision is sealed in a hash-chained audit log. EU-hosted.3MIT- AlicenseAqualityCmaintenanceBiometric authorization for AI agent actions via Face ID on iPhone, enabling secure approval of sensitive actions and credential-safe API calls through vault execution.7MIT
- AlicenseNot gradedqualityBmaintenanceA public-safe research prototype for controlling AI-agent tool actions with deterministic policy, risk-based human approval, time-bound authorization and a tamper-evident audit chain.1MIT
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.