agent-guild

guild_preflight

Run this in the moment BEFORE you delegate to, or pay, an agent endpoint you did not write. Free, no key, one call.

api_key (optional): your registered Guild key, so a later guild_preflight_outcome from the same key joins as the same participant (identity continuity — not a claim of independence). Presenting a key never changes the verdict; an invalid key is refused, not ignored.

Separates what the endpoint CLAIMS from what it just PROVED, live. Measured across the live ecosystem on 2026-07-31: 92.9% of registry-listed agents report healthy but only 33.9% actually complete a task; 0.8% sign their Agent Card; and of agents advertising payment, 5.7% actually return a 402. x402 exact transfers are irreversible, so this has to happen before the payment, not after it.

Unlike a directory badge this is not cached and not derived from a repository at publication time — a server can change its tool descriptions after any one-off review. Checks it could not perform are returned as unknowns and are excluded from the verdict rather than averaged into it.

Example: guild_preflight(url="https://some-agent.example/a2a")

Input Schema

Name	Required	Description	Default
`url`	Yes
`api_key`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 19, 2026
- addedInput schema / properties / api_key
```
Added value: +{
+  "default": "",
+  "type": "string"
+}
```
AddedJul 31, 2026

TDQS

A4.3/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so well: cost ('Free, no key, one call'), freshness ('not cached and not derived from a repository'), error handling ('an invalid key is refused, not ignored'), verdict composition ('Checks it could not perform are returned as `unknowns` and are excluded from the verdict'), and the guarantee that a key never changes the verdict.

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-loads the imperative trigger, then uses a labeled 'api_key (optional):' block and a short supporting rationale. The ecosystem-statistics sentence (92.9% vs 33.9%, 0.8% signing, 5.7% 402) is dense but earns its place by justifying the tool's existence and the pre-payment timing.

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?

An output schema exists, so return-shape explanation is not needed, and the description still covers cost, key behavior, caching/freshness, unknown handling, and the urgency of pre-payment use. For a two-parameter preflight check it leaves no significant operational question unanswered.

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 description coverage is 0%, so the description must compensate, and it does so thoroughly for api_key (optional registration key, identity continuity, does not affect verdict, invalid keys refused). The required `url` parameter is only conveyed by the example invocation rather than explained, which is a minor gap.

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?

States a precise verb and object — check an external agent endpoint right before delegating or paying — and frames the core distinction ('separates what the endpoint CLAIMS from what it just PROVED, live'). It does not, however, explicitly differentiate itself from close siblings like guild_preflight_deep, guild_preflight_outcome, or guild_check, leaving the agent to infer the boundary.

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?

Gives a clear trigger ('in the moment BEFORE you delegate to, or pay, an agent endpoint you did not write') and reinforces timing with the irreversibility of x402 `exact` transfers. It references the follow-on tool guild_preflight_outcome for identity continuity, but offers no explicit when-not-to-use or comparison against the deep variant.

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

All agent-guild 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.