Conduit Agentic Commerce

Create agent profile

agent_create

Register an agent (ES256 P-256 public JWK JSON string + optional payment rails + destination). BEFORE: list ~/.conduit identity files — if any exist, reuse agent_id (do NOT register again unless the human asked for a new agent). AFTER: write persist.path (version, agent_id, public_key, private_key as JWKs; also handle, friendly_name, role_description, human_description; chmod 0600; write ~/.conduit/active). Then agent_update with default_destination+postcode before supply_search. Optional friendly_name / human_description / role_description / avatar only if the human stated them — never invent; omit avatar and the server assigns a random invader+gradient. Omit handle to auto-generate (e.g. parcel-watcher-12).

Input Schema

TableJSON Schema

Name	Required	Description
`avatar`	No	Identity mark. Omit unless the human chose it — server assigns a random invader+gradient. { kind:"glyph", glyph:"invader"\|emoji, tint?:invader color, gradient } or { kind:"image", src }. Tint only for invader. Do not store in the credentials file.
`handle`	No	Optional display handle (lowercase kebab); omit to auto-generate e.g. parcel-watcher-12
`public_key`	Yes	ES256 P-256 public JWK as a JSON string (kty=EC, crv=P-256, x, y). Not PEM, hex, or base64url-wrapped JSON. Keep the matching private JWK only in ~/.conduit/{handle}.credentials.json.
`preferences`	No	Optional agent preference bag
`friendly_name`	No	Human-facing label (≠ handle), e.g. EU Restock Bot
`payment_rails`	No	Optional rail keys to seed, e.g. ["x402"]
`business_profile`	No	Optional business profile metadata object
`role_description`	No	Self-instruction for this agent only, e.g. manage EU supplies
`human_description`	No	Description shown to humans on the org dashboard
`default_destination`	No	Where orders ship. postcode + country is enough for supply_search and delivery estimates; add address, locality and region so checkout links arrive prefilled.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`hint`	No
`next`	No
`error`	No
`nonce`	No
`avatar`	No
`detail`	No
`handle`	No
`persist`	No
`agent_id`	No
`mandates`	No
`terminal`	No
`challenge`	No
`created_at`	No
`public_key`	No
`reputation`	No
`open_orders`	No
`permissions`	No
`preferences`	No
`organization`	No
`total_orders`	No
`friendly_name`	No
`payment_rails`	No
`organization_id`	No
`business_profile`	No
`role_description`	No
`human_description`	No
`destination_source`	No
`default_destination`	No
`effective_destination`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 24, 2026
- addedOutput schema / properties / next / properties / args / additionalProperties / anyOf
```
Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "type": "boolean"
+  }
+]
```
- removedOutput schema / properties / next / properties / args / additionalProperties / type
```
Removed value: -"string"
```

Changed4 schema fields changedSep 7, 2026

addedInput schema / properties / default_destination / additionalProperties
```
Added value: +{}
```

changedInput schema / properties / default_destination / description

Previous value: -"Shipping destination object; include postcode before supply_search"New value: +"Where orders ship. postcode + country is enough for supply_search and delivery estimates; add address, locality and region so checkout links arrive prefilled."

addedInput schema / properties / default_destination / properties

Added value: +{
+  "address": {
+    "description": "Street address. Needed for checkout to prefill",
+    "type": "string"
+  },
+  "city": {
+    "description": "Alias of locality",
+    "type": "string"
+  },
+  "country": {
+    "description": "ISO country code, e.g. US",
+    "type": "string"
+  },
+  "email": {
+    "description": "Buyer contact email for the merchant order",
+    "type": "string"
+  },
+  "locality": {
+    "description": "City. Needed for checkout to prefill",
+    "type": "string"
+  },
+  "name": {
+    "description": "Recipient name; many merchants require it to fulfil",
+    "type": "string"
+  },
+  "phone": {
+    "description": "Buyer phone in E.164, e.g. +12125550188",
+    "type": "string"
+  },
+  "postal_code": {
+    "description": "Alias of postcode",
+    "type": "string"
+  },
+  "postcode": {
+    "description": "Postal / ZIP code. Enough for search and delivery estimates",
+    "type": "string"
+  },
+  "region": {
+    "description": "State / province",
+    "type": "string"
+  },
+  "state": {
+    "description": "Alias of region",
+    "type": "string"
+  },
+  "street_address": {
+    "description": "Alias of address",
+    "type": "string"
+  }
+}

addedInput schema / properties / default_destination / type
```
Added value: +"object"
```

Changed24 schema fields changedAug 29, 2026
- removedOutput schema / properties / agentId
```
Removed value: -{
-  "type": "string"
-}
```
- addedOutput schema / properties / agent_id
```
Added value: +{
+  "type": "string"
+}
```
- removedOutput schema / properties / businessProfile
```
Removed value: -{}
```
- addedOutput schema / properties / business_profile
```
Added value: +{}
```
- removedOutput schema / properties / createdAt
```
Removed value: -{
-  "type": "string"
-}
```
- addedOutput schema / properties / created_at
```
Added value: +{
+  "type": "string"
+}
```
- removedOutput schema / properties / defaultDestination
```
Removed value: -{}
```
- addedOutput schema / properties / default_destination
```
Added value: +{}
```
- removedOutput schema / properties / effectiveDestination
```
Removed value: -{}
```
- addedOutput schema / properties / effective_destination
```
Added value: +{}
```
- removedOutput schema / properties / friendlyName
```
Removed value: -{
-  "type": "string"
-}
```
- addedOutput schema / properties / friendly_name
```
Added value: +{
+  "type": "string"
+}
```
- removedOutput schema / properties / humanDescription
```
Removed value: -{
-  "type": "string"
-}
```
- addedOutput schema / properties / human_description
```
Added value: +{
+  "type": "string"
+}
```
- removedOutput schema / properties / openOrders
```
Removed value: -{}
```
- addedOutput schema / properties / open_orders
```
Added value: +{}
```
- removedOutput schema / properties / paymentRails
```
Removed value: -{
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}
```
- addedOutput schema / properties / payment_rails
```
Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
```
- removedOutput schema / properties / publicKey
```
Removed value: -{
-  "type": "string"
-}
```
- addedOutput schema / properties / public_key
```
Added value: +{
+  "type": "string"
+}
```
- removedOutput schema / properties / roleDescription
```
Removed value: -{
-  "type": "string"
-}
```
- addedOutput schema / properties / role_description
```
Added value: +{
+  "type": "string"
+}
```
- removedOutput schema / properties / totalOrders
```
Removed value: -{}
```
- addedOutput schema / properties / total_orders
```
Added value: +{}
```

Changed4 schema fields changedAug 28, 2026

addedInput schema / properties / avatar

Added value: +{
+  "description": "Identity mark. Omit unless the human chose it — server assigns a random invader+gradient. { kind:\"glyph\", glyph:\"invader\"|emoji, tint?:invader color, gradient } or { kind:\"image\", src }. Tint only for invader. Do not store in the credentials file."
+}

changedInput schema / properties / public_key / description

Previous value: -"ES256 P-256 public JWK as a JSON string (kty=EC, crv=P-256, x, y). Not PEM, hex, or base64url-wrapped JSON. Keep the matching private JWK only in ~/.conduit/credentials.json."New value: +"ES256 P-256 public JWK as a JSON string (kty=EC, crv=P-256, x, y). Not PEM, hex, or base64url-wrapped JSON. Keep the matching private JWK only in ~/.conduit/{handle}.credentials.json."

addedOutput schema / properties / avatar
```
Added value: +{}
```

addedOutput schema / properties / permissions

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed1 schema field changedJul 28, 2026

changedInput schema / properties / public_key / description

Previous value: -"Agent public key (hex or base64) for challenge-response auth"New value: +"ES256 P-256 public JWK as a JSON string (kty=EC, crv=P-256, x, y). Not PEM, hex, or base64url-wrapped JSON. Keep the matching private JWK only in ~/.conduit/credentials.json."

AddedJul 26, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Discloses substantial side effects beyond annotations: writes persist.path with chmod 0600, writes ~/.conduit/active, auto-generates handle/avatar defaults, and explicitly forbids inventing optional profile fields. This description carries the behavioral burden thoroughly despite annotations only providing mutability/read-only hints.

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 description is long but dense and deliberately organized with BEFORE/AFTER sections; each segment carries actionable guidance. Purpose is front-loaded, though some schema details are restated, making it slightly verbose rather than truly concise.

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 10-parameter tool with nested objects and side effects, the description covers preconditions, file writes, permissions, defaults, sequencing, and the policy on optional fields. An output schema exists, so return-value documentation is not the description's burden; nothing essential 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 baseline is 3. The description adds meaningful invocation semantics: include optional friendly_name/human_description/role_description/avatar only if the human stated them, omit avatar to get a random server-assigned mark, and omit handle to auto-generate like parcel-watcher-12. Minor gap: preferences and business_profile are only covered by the general 'never invent' rule.

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 specific verb and resource: 'Register an agent' with the required ES256 P-256 public JWK plus optional rails/destination. It also differentiates from siblings by directing reuse of an existing agent_id and pointing to agent_update for later destination changes.

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 BEFORE condition: list ~/.conduit identity files)Skip now? Actually just output JSON. Need ensure valid.If any exist, reuse agent_id and do NOT register again unless the human asked for a new agent. It also specifies an AFTER sequence: write persist.path, then call agent_update with default_destination+postcode before supply_search, giving the agent clear routing versus alternatives.

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

All Conduit Agentic Commerce 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.

Resources

Need Help?