Surface contracts: API behavior evidence, x402 pre-payment check, MCP server preflight
Scored across 7 tools
Most tools have clearly distinct targets: list vs. get contract vs. get recipe vs. verify vs. contribute are separable, and the two probe tools (preflight_mcp_server, prepay_check) hit different resources (MCP endpoints vs. x402 payment routes). Minor overlap exists where get_surface_contract and verify_surface both surface per-claim status, but descriptions make the retrieve-vs-run distinction clear.
All names are snake_case and most follow a verb_noun pattern (get_surface_contract, list_surface_contracts, verify_surface, contribute_discrepancy). preflight_mcp_server and prepay_check deviate slightly by leading with a noun-ish term, but the convention remains readable and predictable.
Seven tools is well-scoped for a contract-registry-plus-probing server, with each tool earning its place (discovery, retrieval, verification, contribution, and two external probes). No redundant or bloated entries.
The surface covers discovery, contract/recipe retrieval, verification, contribution, and pre-commit probing of MCP and payment endpoints, forming a coherent lifecycle. A minor gap is the absence of a tool to read back filed contributions/proposals (the GET /v1/contributions listing is referenced but not exposed), which agents must work around.
Report a platform behaviour that contradicts a published claim, or a new claim, with evidence. One-line call: POST /v1/contribute with {contractId, kind, statement, evidence[], reporter, observedAt}. Stored as pending; a published contract is never changed without independent verification. A contractId no published contract serves is accepted as a NEW-PLATFORM PROPOSAL: the 202 body carries contractExists:false (with proposal:true, proposedContractId and proposedHost), it is listed distinctly at GET /v1/contributions, and it stays pending until a second party reproduces it - it never creates or mutates a contract. A proposal filed by us reads selfProbe:true in that listing, and GET /v1/contributions counts proposals filed by non-self submitters separately from our own self-probes, so only the non-self number is outside coverage.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| claimId | No | ||
| evidence | Yes | ||
| reporter | No | your agent or operator name, so the record is attributed to you and is not read as one of ours (an unattributed record is counted non-self AND flagged noReporter) | |
| statement | Yes | ||
| contractId | Yes | the platform's contract id or host; an id no published contract serves is accepted as a new-platform proposal (contractExists:false) | |
| observedAt | No | ISO 8601 date you observed the behaviour; a claim without a date is not a measurement |
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 richly: records are stored as pending, a published contract is never changed without independent verification, a proposal never creates or mutates a contract, and it stays pending until a second party reproduces it. This is exactly the non-obvious mutation-safety context an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded, but the description runs as one dense paragraph and drifts into response-level detail (202 body fields, selfProbe:true, how GET /v1/contributions counts proposals) that is closer to output-schema material than selection guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutation tool with no annotations and no output schema, the description is unusually complete about lifecycle and safety semantics. The remaining gap is the unexplained kind/claimId parameters and the fact that return format is only partially sketched.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 43%, so the description must compensate; it does explain contractId (unserved id becomes a proposal), reporter attribution, and observedAt format. But it says nothing about the kind enum values (discrepancy vs new-claim vs independent-confirmation) or claimId, leaving those parameters unexplained in both places.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource: report a platform behaviour contradicting a published claim (or a new claim) with evidence. It is clearly a write/contribute operation distinct from the read-oriented siblings (get_surface_contract, list_surface_contracts), but it never names an alternative to disambiguate against them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete condition for use ('a platform behaviour that contradicts a published claim') and an implicit routing rule (a contractId no published contract serves becomes a new-platform proposal). However, it names no alternatives and offers no explicit when-not guidance, so the agent must infer the boundary with verify_surface.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a plain-text integration recipe for a platform: the order of operations to use it, and a guard clause for every behaviour we measured going wrong, each naming the contract claim behind it. Derived from the contract, so it cannot drift from it.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | contract id or host, e.g. moltbook |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it does disclose meaningful traits: output is plain text, it contains ordered operations plus one guard clause per observed failure mode, and it is derived from the contract so it cannot drift (a freshness/determinism guarantee). It does not mention permissions, rate limits, or failure behavior, but for a read-only 'get' it covers the important ground.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences with the verb and resource front-loaded, then the artifact's contents, then the trust guarantee. No filler or repetition; every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must characterize the return, and it does: plain text, ordered operations, guard clauses tied to contract claims. For a single-parameter lookup tool this is close to sufficient, with only auth/error behavior left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter and schema description coverage is 100% ('contract id or host, e.g. moltbook'), so the schema already does the heavy lifting and baseline is 3. The description adds only that the id identifies 'a platform', marginally reinforcing but not extending the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('Get a plain-text integration recipe for a platform') and states what the artifact contains: order of operations plus guard clauses. The resource is clearly distinct from siblings like get_surface_contract or verify_surface, though no sibling is named explicitly to sharpen the contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer you call this when you need step-by-step integration guidance for a platform. There is no explicit when-to-use/when-not statement and no routing against get_surface_contract, verify_surface, or preflight_mcp_server, which is the main gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the machine-readable surface contract for a platform host (read/write semantics, pending states, rate limits, limits, idempotency, pagination completeness, data portability), each claim carrying its evidence and its verification status.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | contract id or host, e.g. moltbook or www.moltbook.com |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that the output is machine-readable and that each claim carries evidence and a verification status, but it says nothing about auth requirements, caching, failure behavior for unknown hosts, or the read-only nature of the call (only implied by "Get").
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with the verb and resource front-loaded. The long parenthetical inventory of contract contents is dense but every item earns its place by telling the agent what the payload covers; it could be tightened but is not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must describe the return value, and it does list the claim categories plus the evidence and verification-status structure. It stops short of stating the serialization format or error behavior, but is adequate for a one-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single id parameter already documents its format with examples ("moltbook or www.moltbook.com"). The description adds no further parameter meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ("Get") plus a precise resource ("machine-readable surface contract for a platform host") and an enumerated field list that makes clear what the contract contains. The singular-host scope implicitly separates it from list_surface_contracts, though no sibling is named outright.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer you call this when you need the contract details for a specific host id. There is no statement of when to prefer this over verify_surface or list_surface_contracts, and no prerequisites or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the platform surface contracts published in Penny's free registry, with claim counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It hints that the registry is 'free' and that results include claim counts, but says nothing about read-only nature, ordering, pagination, or result size for what could be a large listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. The resource and the distinguishing output detail both land immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and no parameters, the description must stand alone, and it covers what the tool returns at a high level. It omits ordering, pagination, and completeness characteristics that would help an agent consume a listing result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a no-parameter tool applies. No parameter-level semantics are needed or missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('platform surface contracts published in Penny's free registry'), and the plural framing naturally separates it from the singular sibling get_surface_contract. It adds the output detail 'with claim counts', though it never names the sibling it complements.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are referenced. Usage is only inferable from the verb 'List', which for a zero-parameter tool is weak but not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the anonymous MCP handshake against ANY https MCP endpoint you name, right now, and get back a verdict (open / refused / unreachable / initialize-transport-error), the shape of any refusal body, whether the server is stateful (sets Mcp-Session-Id), how many tools tools/list returns, and the guard clauses that follow. Use it before wiring an MCP server into your own config. Pass urls (up to 5) to check a whole mcp.json in one call. When the endpoint refuses, it also reports whether the refusal advertises a credential path (an RFC 9728 resource_metadata pointer) and whether that pointer resolves to a metadata document naming an authorization server, so you learn where a token would come from without writing that parsing yourself. No credential is sent, none is obtained, and none of their tools is ever called.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | absolute https URL of the MCP endpoint, e.g. https://host/mcp | |
| urls | No | batch form: 2 to 5 absolute https URLs, checked with the same battery in one call (each one counts against the same daily egress budget as a single preflight) |
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: it discloses the side-effect profile ('No credential is sent, none is obtained, and none of their tools is ever called'), reports statefulness via Mcp-Session-Id, distinguishes refusal bodies, and explains the RFC 9728 resource_metadata resolution it performs. This is unusually rich behavioral context for a probe tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core verb and outcome, and every clause adds actionable detail (verdict taxonomy, credential-safety guarantee, RFC 9728 pointer behavior). It is dense and slightly overlong, but few sentences are expendable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must describe return values, and it does: it enumerates the verdict set, refusal body shape, statefulness, tool count, and authorization-server discovery. Coupled with a 100%-covered input schema, an agent has enough to call and interpret the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 meaning beyond the schema: it explains that `urls` checks a whole mcp.json in one call, is capped at 5, and shares a daily egress budget. It does not, however, clarify how `url` and `urls` interact or whether both may be supplied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (run the MCP handshake against any https endpoint) and enumerates the precise outputs it returns (verdict values, statefulness, tool count, guard clauses). This is clearly separable from siblings like verify_surface or get_surface_contract, which concern surfacing contracts rather than live endpoint preflight.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit use condition: 'Use it before wiring an MCP server into your own config.' This frames the when-to-use well, but it names no alternative tool or exclusion, leaving the agent to infer when verification/preflight is not appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check an x402 route BEFORE you pay it. GET /v1/prepay?url= makes ONE unpaid GET with no payment header and no credential, and returns one row: the measured HTTP status, the parsed x402 v2 challenge (scheme / network / asset / amount / payTo), whether that challenge is schema-valid exact-on-Base, and whether its payTo and price agree with the seller's own card (pass card to read that card with one more unpaid GET). No payment is made, no credential is sent, no redirect is followed, and a transport failure on our side is reported as unknown rather than as a fact about the seller. Use it to gate a payment decision on measured terms instead of on a seller's prose.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | absolute https URL of the route you are about to pay | |
| card | No | optional: absolute https URL of the seller's own card/listing page, read with one more unpaid GET to compare the wallet and the price it advertises (agreement is true|false|unknown, and unknown is null, never false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does so richly: exactly ONE unpaid GET, no payment header, no credential, no redirect followed, and transport failure on the server side is reported as 'unknown' rather than as a fact about the seller. It also enumerates what the returned row contains, which is the behavioral detail an agent needs to trust the result.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first short sentence and nothing is filler, but the second sentence is an unusually long chain of clauses that packs return shape, safety guarantees, and failure semantics into one breath. Dense but still parseable, so slightly below ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description must define both the safety profile and the return payload, and it does: it lists the measured status, the parsed x402 v2 challenge fields, schema-validity, and card agreement semantics. An agent has everything needed to interpret a result and to decide whether to pay.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and the schema already documents both `url` and `card`. The description adds decision-level meaning by framing `card` as reading the seller's advertised wallet/price with one more unpaid GET so the agent understands why it would supply the optional parameter, a modest increment over the schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Check an x402 route') plus its timing constraint ('BEFORE you pay it') and the exact operation behind it (GET /v1/prepay?url=...). This is clearly distinct from the sibling tools about surface contracts and MCP preflight, so an agent can route to it without opening any other schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit use case: 'Use it to gate a payment decision on measured terms instead of on a seller's prose,' which tells the agent this is a pre-payment verification step. It does not name a concrete alternative tool or a when-not-to-use condition, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the anonymous conformance checks for a contract now and return verified / failed / unknown / manual / unsupported per claim.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that the checks are "anonymous" (no auth implied) and enumerates the five possible per-claim outcomes, but says nothing about side effects, whether it is read-only, cost, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the enumerated status values are high-value and earn their space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema, the description supplies the return vocabulary (verified/failed/unknown/manual/unsupported per claim), which is the key missing structured info. Remaining gaps are the exact meaning of "id" and any safety/authentication profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the single parameter is opaque ("id"). The phrase "for a contract" implies the id identifies a surface contract, which partially compensates, but it never states this explicitly or gives the id's format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource: it runs anonymous conformance checks for a contract and returns per-claim verdicts. This clearly separates it from siblings like get_surface_contract (which retrieves) and preflight_mcp_server, though it doesn't explicitly name those alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no prerequisites, and no routing against the sibling tools. The word "now" hints at immediate/synchronous execution versus some deferred alternative, but that inference is left to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
prepay_checkcontribute_discrepancy3 fields changedInput schema / properties / contractId / descriptionAdded value: +"the platform's contract id or host; an id no published contract serves is accepted as a new-platform proposal (contractExists:false)"Input schema / properties / observedAtAdded value: +{
+ "description": "ISO 8601 date you observed the behaviour; a claim without a date is not a measurement",
+ "type": "string"
+}Input schema / properties / reporterAdded value: +{
+ "description": "your agent or operator name, so the record is attributed to you and is not read as one of ours (an unattributed record is counted non-self AND flagged noReporter)",
+ "type": "string"
+}preflight_mcp_server2 fields changedInput schema / properties / urlsAdded value: +{
+ "description": "batch form: 2 to 5 absolute https URLs, checked with the same battery in one call (each one counts against the same daily egress budget as a single preflight)",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / requiredRemoved value: -[
- "url"
-]preflight_mcp_serverget_integration_recipecontribute_discrepancyget_surface_contractlist_surface_contractsverify_surfaceAgent-native MCP for governed commerce, x402 payments, paid capabilities, and verifiable receipts.
Contract-change authorization for AI agents: preflight a change to an API or MCP contract, get a signed decision, and verify the receipt offline. Only a granted change can proceed.
Remote MCP utilities for agents: structured data, commerce checks, and x402 paid API discovery.
Cross-border preflight, x402 quote and evidence receipts for A2A/MCP agent workflows.
Add one secure layer between your agents and this server.
