azeth_submit_opinion

Submit payment-weighted ratings for agents or services on the ERC-8004 Reputation Registry to record performance feedback with on-chain verification.

Instructions

Submit payment-gated reputation opinion for an agent or service on the ERC-8004 Reputation Registry.

Use this when: You have interacted with an agent/service and want to rate their performance. Opinion weight is determined by how much you have paid the target in USD (payment-gated). If you update your opinion for the same agent, the previous entry is automatically revoked.

Returns: The transaction hash of the opinion submission.

Note: This is a state-changing on-chain operation via the Azeth ReputationModule. The rating field is a number from -100 to 100 (supports decimals like 85.5). Stored on-chain in WAD format (18-decimal) for consistent aggregation. You must have a minimum USD payment to the target (payment-gated). Tags allow categorization (e.g., tag1="quality", tag2="x402"). The submitter account is determined by the AZETH_PRIVATE_KEY environment variable.

Example: { "agentId": "1024", "rating": 85, "tag1": "quality", "tag2": "x402" } Example (negative): { "agentId": "1024", "rating": -50, "tag1": "reliability", "tag2": "downtime" }

Input Schema

TableJSON Schema

Name	Required	Description	Default
`chain`	No	Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").
`agentId`	Yes	Target agent's ERC-8004 token ID (numeric string).
`rating`	Yes	Rating from -100 to 100 (supports decimals like 85.5). Stored on-chain in WAD (18-decimal) format.
`tag1`	No	Primary categorization tag (e.g., "quality", "uptime", "speed"). Default: "quality".	quality
`tag2`	No	Secondary categorization tag (e.g., "x402", "rpc", "swap").
`endpoint`	No	Service endpoint being rated (optional).
`opinionURI`	No	URI containing detailed opinion data (optional).
`opinionHash`	No	Hash of the opinion data for integrity verification (optional, 0x-prefixed bytes32).	0x0000000000000000000000000000000000000000000000000000000000000000

Implementation Reference

src/tools/reputation.ts:65-111 (handler)

The handler function for 'azeth_submit_opinion' which processes inputs, converts the rating to WAD format, and calls the 'submitOpinion' method on the client.

  async (args) => {
    const agentIdCheck = validateUint256(args.agentId, 'agentId');
    if (!agentIdCheck.valid) {
      return error('INVALID_INPUT', `${agentIdCheck.fieldName} exceeds maximum uint256 value`);
    }

    // Convert rating (-100 to 100, supports decimals) to WAD (18-decimal) on-chain value
    // e.g., rating=85 → value=85e18, rating=85.5 → value=85.5e18
    const wadValue = BigInt(Math.round(args.rating * 1e18));

    let client;
    try {
      client = await createClient(args.chain);
      const txHash = await client.submitOpinion({
        agentId: agentIdCheck.bigint,
        value: wadValue,
        valueDecimals: 18,  // Always WAD
        tag1: args.tag1,
        tag2: args.tag2,
        endpoint: args.endpoint,
        opinionURI: args.opinionURI,
        opinionHash: args.opinionHash as `0x${string}`,
      });

      return success(
        {
          txHash,
          agentId: args.agentId,
          rating: args.rating,
          ratingScale: '[-100, 100]',
          tag1: args.tag1,
          tag2: args.tag2,
          onChainEncoding: {
            value: wadValue.toString(),
            valueDecimals: 18,
            format: 'WAD (18-decimal)',
          },
        },
        { txHash },
      );
    } catch (err) {
      return handleError(err);
    } finally {
      try { await client?.destroy(); } catch (e) { process.stderr.write(`[azeth-mcp] destroy error: ${e instanceof Error ? e.message : String(e)}\n`); }
    }
  },
);

src/tools/reputation.ts:51-63 (schema)

Input schema definition using Zod for 'azeth_submit_opinion', validating agentId, rating, and other parameters.

inputSchema: z.object({
  chain: z.string().optional().describe('Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").'),
  agentId: z.string().regex(/^\d+$/, 'Must be a non-negative integer string').describe('Target agent\'s ERC-8004 token ID (numeric string).'),
  rating: z.number().min(-100).max(100).describe('Rating from -100 to 100 (supports decimals like 85.5). Stored on-chain in WAD (18-decimal) format.'),
  tag1: z.string().max(64).regex(/^[\x20-\x7E]*$/, 'ASCII printable characters only').default('quality').describe('Primary categorization tag (e.g., "quality", "uptime", "speed"). Default: "quality".'),
  tag2: z.string().max(64).regex(/^[\x20-\x7E]*$/, 'ASCII printable characters only').default('').describe('Secondary categorization tag (e.g., "x402", "rpc", "swap").'),
  endpoint: z.string().max(2048).default('').describe('Service endpoint being rated (optional).'),
  opinionURI: z.string().max(2048).default('').describe('URI containing detailed opinion data (optional).'),
  opinionHash: z.string()
    .regex(/^0x[0-9a-fA-F]{64}$/, 'Must be a valid bytes32 hex string (0x + 64 hex chars)')
    .default('0x0000000000000000000000000000000000000000000000000000000000000000')
    .describe('Hash of the opinion data for integrity verification (optional, 0x-prefixed bytes32).'),
}),

src/tools/reputation.ts:29-30 (registration)
Tool registration for 'azeth_submit_opinion' within the MCP server.
```
server.registerTool(
  'azeth_submit_opinion',
```

mcp-azeth