@xfxstudio/claworld 0.1.3 → 0.1.4

package/src/openclaw/plugin/register.js

@@ -2,18 +2,11 @@ import { createClaworldChannelPlugin } from './claworld-channel-plugin.js';
 import {
   projectToolChatRequestListResponse,
   projectToolChatRequestMutationResponse,
-  projectToolBroadcastWorldResponse,
-  projectToolWorldList,
   projectToolCreateWorldResponse,
+  projectToolWorldList,
   projectToolFeedbackSubmissionResponse,
-  projectToolFriendRequestListResponse,
-  projectToolFriendRequestMutationResponse,
   projectToolJoinWorldResponse,
-  projectToolManagedWorldResponse,
-  projectToolOwnedWorldsResponse,
-  projectToolSearchWorldResponse,
   projectToolWorldDetail,
-  projectToolWorldProfileCollectionResponse,
 } from '../runtime/tool-contracts.js';
 import { CLAWORLD_TOOL_CONTRACT_VERSION } from '../runtime/tool-inventory.js';
 import { setClaworldRuntime } from './runtime.js';
@@ -81,53 +74,6 @@ function resolveProfileDraftParams(params = {}, { includeProfileSnapshot = false
   };
 }
 
-const CANONICAL_AGENT_CODE_PATTERN = '^[A-Za-z0-9._:+~-]+@[A-Za-z0-9._:+~-]+$';
-const CANONICAL_AGENT_CODE_REGEX = new RegExp(CANONICAL_AGENT_CODE_PATTERN, 'i');
-
-function requireRelayAgentSelector(params = {}, { codeKey, idKey, legacyTargetKey = null, label = 'relay target' } = {}) {
-  const agentCode = normalizeText(params[codeKey], null);
-  const agentId = normalizeText(params[idKey], null);
-  const legacyTarget = legacyTargetKey ? normalizeText(params[legacyTargetKey], null) : null;
-
-  if (agentId) {
-    return {
-      agentId,
-      agentCode,
-      legacyTarget,
-    };
-  }
-
-  const candidateAgentCode = agentCode || legacyTarget;
-  if (!candidateAgentCode) {
-    throw createRuntimeBoundaryError({
-      code: 'tool_input_invalid',
-      category: 'input',
-      status: 400,
-      message: `claworld ${label} requires ${idKey} or ${codeKey}`,
-      publicMessage: `claworld ${label} requires ${idKey} or ${codeKey}`,
-      recoverable: true,
-      context: { label, codeKey, idKey },
-    });
-  }
-  if (!CANONICAL_AGENT_CODE_REGEX.test(candidateAgentCode)) {
-    throw createRuntimeBoundaryError({
-      code: 'tool_input_invalid',
-      category: 'input',
-      status: 400,
-      message: `claworld ${codeKey} must use local@namespace agentCode schema`,
-      publicMessage: `claworld ${codeKey} must use local@namespace agentCode schema`,
-      recoverable: true,
-      context: { label, codeKey, value: candidateAgentCode },
-    });
-  }
-
-  return {
-    agentId: null,
-    agentCode: candidateAgentCode.toLowerCase(),
-    legacyTarget,
-  };
-}
-
 function buildClaworldStatusRoute(plugin) {
   return {
     method: 'GET',
@@ -243,57 +189,160 @@ async function resolveToolContext(api, plugin, params = {}) {
   };
 }
 
-async function resolveRelayTargetAddress(plugin, context, params = {}, {
-  codeKey,
-  idKey,
-  legacyTargetKey = null,
-  label = 'target agent',
+function cloneMetadataValue(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function stringParam({
+  description = null,
+  minLength = null,
+  enumValues = null,
+  pattern = null,
+  examples = [],
 } = {}) {
-  const selector = requireRelayAgentSelector(params, {
-    codeKey,
-    idKey,
-    legacyTargetKey,
-    label,
-  });
-  const payload = await plugin.helpers.pairing.resolveAgentIdentity({
-    ...context,
-    agentCode: selector.agentCode,
-    agentId: selector.agentId,
-    address: selector.legacyTarget,
-  });
-  if (!payload.address) {
-    throw createRuntimeBoundaryError({
-      code: 'target_not_found',
-      category: 'input',
-      status: 404,
-      message: `claworld ${label} not found`,
-      publicMessage: `claworld ${label} not found`,
-      recoverable: true,
-      context: { label, codeKey, idKey },
-    });
-  }
   return {
-    selector,
-    payload,
-    toAddress: payload.address,
+    type: 'string',
+    ...(description ? { description } : {}),
+    ...(Number.isInteger(minLength) && minLength > 0 ? { minLength } : {}),
+    ...(Array.isArray(enumValues) && enumValues.length > 0 ? { enum: enumValues } : {}),
+    ...(pattern ? { pattern } : {}),
+    ...(Array.isArray(examples) && examples.length > 0 ? { examples } : {}),
+  };
+}
+
+function integerParam({
+  description = null,
+  minimum = null,
+  maximum = null,
+  examples = [],
+} = {}) {
+  return {
+    type: 'integer',
+    ...(description ? { description } : {}),
+    ...(Number.isInteger(minimum) ? { minimum } : {}),
+    ...(Number.isInteger(maximum) ? { maximum } : {}),
+    ...(Array.isArray(examples) && examples.length > 0 ? { examples } : {}),
+  };
+}
+
+function objectParam({
+  description = null,
+  properties = {},
+  required = [],
+  additionalProperties = false,
+  examples = [],
+} = {}) {
+  return {
+    type: 'object',
+    additionalProperties,
+    ...(description ? { description } : {}),
+    ...(Array.isArray(required) && required.length > 0 ? { required } : {}),
+    properties,
+    ...(Array.isArray(examples) && examples.length > 0 ? { examples: examples.map(cloneMetadataValue) } : {}),
+  };
+}
+
+function arrayParam({
+  description = null,
+  items = {},
+  maxItems = null,
+  examples = [],
+} = {}) {
+  return {
+    type: 'array',
+    items,
+    ...(description ? { description } : {}),
+    ...(Number.isInteger(maxItems) ? { maxItems } : {}),
+    ...(Array.isArray(examples) && examples.length > 0 ? { examples: examples.map(cloneMetadataValue) } : {}),
+  };
+}
+
+function buildToolMetadata({
+  category,
+  usageNotes = [],
+  examples = [],
+} = {}) {
+  return {
+    surface: 'canonical_public',
+    canonical: true,
+    category: normalizeText(category, 'general'),
+    usageNotes: Array.isArray(usageNotes) ? usageNotes.filter(Boolean) : [],
+    examples: Array.isArray(examples)
+      ? examples.map((example) => cloneMetadataValue(example)).filter(Boolean)
+      : [],
   };
 }
 
 function buildRegisteredTools(api, plugin) {
+  const accountIdProperty = stringParam({
+    description: 'Claworld account id to execute the tool against. In managed installs this is usually the dedicated claworld account.',
+    minLength: 1,
+    examples: ['claworld'],
+  });
+  const worldIdProperty = stringParam({
+    description: 'Canonical world id returned by claworld_list_worlds or claworld_get_world_detail.',
+    minLength: 1,
+    examples: ['dating-demo-world'],
+  });
+  const profileObjectProperty = (description, examples = []) => objectParam({
+    description,
+    additionalProperties: true,
+    examples,
+  });
+
   return [
     {
       name: 'claworld_list_worlds',
-      description: 'List the available Claworld worlds for the current channel account.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
+      label: 'Claworld List Worlds',
+      description: 'Canonical first-step discovery tool. List the available Claworld worlds for the current account before fetching one world detail.',
+      metadata: buildToolMetadata({
+        category: 'world_discovery',
+        usageNotes: [
+          'Use after claworld_pair_agent when the user wants to browse worlds.',
+          'After the user picks one world, call claworld_get_world_detail.',
+        ],
+        examples: [
+          {
+            title: 'Browse hot worlds',
+            input: {
+              accountId: 'claworld',
+              sort: 'hot',
+              limit: 10,
+            },
+            outcome: 'Returns a compact world list ordered for first-pass discovery.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Discovery query for browsing the current public world directory.',
         properties: {
-          accountId: { type: 'string' },
-          limit: { type: 'integer', minimum: 1, maximum: 50 },
-          sort: { type: 'string', enum: ['hot', 'latest'] },
-          page: { type: 'integer', minimum: 1 },
+          accountId: accountIdProperty,
+          limit: integerParam({
+            description: 'Maximum number of worlds to return for this page.',
+            minimum: 1,
+            maximum: 50,
+            examples: [10],
+          }),
+          sort: stringParam({
+            description: 'Directory ordering. Use hot for first-pass discovery and latest for recency review.',
+            enumValues: ['hot', 'latest'],
+            examples: ['hot'],
+          }),
+          page: integerParam({
+            description: '1-based directory page number.',
+            minimum: 1,
+            examples: [1],
+          }),
         },
-      },
+        examples: [
+          {
+            accountId: 'claworld',
+            sort: 'hot',
+            limit: 10,
+            page: 1,
+          },
+        ],
+      }),
       async execute(_toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params);
         const payload = await plugin.helpers.postSetup.fetchWorldDirectory({
@@ -307,16 +356,39 @@ function buildRegisteredTools(api, plugin) {
     },
     {
       name: 'claworld_get_world_detail',
-      description: 'Fetch the product-facing world detail for one Claworld world.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
+      label: 'Claworld Get World Detail',
+      description: 'Canonical world-inspection tool. Fetch one world detail before deciding whether to join it.',
+      metadata: buildToolMetadata({
+        category: 'world_discovery',
+        usageNotes: [
+          'Use after the user picks one world from claworld_list_worlds.',
+          'Review required fields and rules, then call claworld_join_world directly when enough profile data is available.',
+        ],
+        examples: [
+          {
+            title: 'Inspect one world before join',
+            input: {
+              accountId: 'claworld',
+              worldId: 'dating-demo-world',
+            },
+            outcome: 'Returns the canonical detail contract including required entry-profile fields.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Fetch the canonical detail contract for one world.',
         required: ['worldId'],
         properties: {
-          accountId: { type: 'string' },
-          worldId: { type: 'string', minLength: 1 },
+          accountId: accountIdProperty,
+          worldId: worldIdProperty,
         },
-      },
+        examples: [
+          {
+            accountId: 'claworld',
+            worldId: 'dating-demo-world',
+          },
+        ],
+      }),
       async execute(_toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params);
         const payload = await plugin.runtime.productShell.fetchWorldDetail({
@@ -326,58 +398,101 @@ function buildRegisteredTools(api, plugin) {
         return buildToolResult(projectToolWorldDetail(payload));
       },
     },
-    {
-      name: 'claworld_prepare_world_join',
-      description: 'Compatibility helper for inspect-first world joins. The canonical agent-facing path is direct claworld_join_world with structured retry fields when profile data is incomplete.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['accountId', 'worldId'],
-        properties: {
-          accountId: { type: 'string' },
-          worldId: { type: 'string', minLength: 1 },
-          profile: { type: 'object' },
-          profileDraft: { type: 'object' },
-          profileUpdate: { type: 'object' },
-          profilePatch: { type: 'object' },
-          maxFieldsPerStep: { type: 'integer', minimum: 1, maximum: 5 },
-        },
-      },
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
-        const profileDraftParams = resolveProfileDraftParams(params);
-        const payload = await plugin.runtime.productShell.resolveWorldProfileCollectionFlow({
-          ...context,
-          worldId: params.worldId,
-          profile: profileDraftParams.profile,
-          profileUpdate: profileDraftParams.profileUpdate,
-          maxFieldsPerStep: params.maxFieldsPerStep ?? 1,
-        });
-        return buildToolResult(projectToolWorldProfileCollectionResponse(payload, {
-          accountId: context.accountId,
-          continueToolName: 'claworld_prepare_world_join',
-          joinToolName: 'claworld_join_world',
-        }));
-      },
-    },
     {
       name: 'claworld_join_world',
-      description: 'Create or confirm a Claworld world membership for the current relay agent. When profile data is incomplete it returns structured missing-field guidance for retrying the same tool; on success it returns the canonical candidate-review payload so the next world step is review candidate feed -> claworld_request_chat.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
+      label: 'Claworld Join World',
+      description: 'Canonical world-entry tool. Retry this same tool with profileDraft plus profileUpdate until the backend stops returning needs_profile; on success it returns candidate-review and request_chat follow-up payloads.',
+      metadata: buildToolMetadata({
+        category: 'world_join',
+        usageNotes: [
+          'This is the only public join entrypoint for the default flow.',
+          'When status is needs_profile, merge the user reply into profileDraft and retry this same tool.',
+          'When status is joined, use candidateDelivery/requestChatAction and move to claworld_request_chat.',
+        ],
+        examples: [
+          {
+            title: 'First join attempt with partial profile',
+            input: {
+              accountId: 'claworld',
+              worldId: 'dating-demo-world',
+              profile: {
+                headline: 'Builder who likes climbing',
+              },
+            },
+            outcome: 'Returns needs_profile with nextMissingField and updated profileDraft.',
+          },
+          {
+            title: 'Retry join with incremental updates',
+            input: {
+              accountId: 'claworld',
+              worldId: 'dating-demo-world',
+              profileDraft: {
+                headline: 'Builder who likes climbing',
+              },
+              profileUpdate: {
+                intent: 'new friends first',
+                location: 'Shanghai',
+                interests: ['running', 'climbing'],
+              },
+            },
+            outcome: 'Returns joined plus candidateDelivery and requestChatAction.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Canonical join request and incremental profile-retry payload.',
         required: ['accountId', 'worldId'],
         properties: {
-          accountId: { type: 'string' },
-          worldId: { type: 'string', minLength: 1 },
-          profile: { type: 'object' },
-          profileDraft: { type: 'object' },
-          profileSnapshot: { type: 'object' },
-          profileUpdate: { type: 'object' },
-          profilePatch: { type: 'object' },
-          maxFieldsPerStep: { type: 'integer', minimum: 1, maximum: 5 },
+          accountId: accountIdProperty,
+          worldId: worldIdProperty,
+          profile: profileObjectProperty(
+            'Initial profile draft to validate against the world join schema.',
+            [{ headline: 'Builder who likes climbing' }],
+          ),
+          profileDraft: profileObjectProperty(
+            'Saved draft returned by a previous claworld_join_world response.',
+            [{ headline: 'Builder who likes climbing', intent: 'new friends first' }],
+          ),
+          profileSnapshot: profileObjectProperty(
+            'Explicit full draft snapshot to validate immediately when you already have all required fields.',
+            [{ headline: 'Builder who likes climbing', intent: 'new friends first', location: 'Shanghai' }],
+          ),
+          profileUpdate: profileObjectProperty(
+            'Incremental updates to merge into profileDraft before revalidation.',
+            [{ location: 'Shanghai', interests: ['running', 'climbing'] }],
+          ),
+          profilePatch: profileObjectProperty(
+            'Compatibility alias for profileUpdate.',
+            [{ location: 'Shanghai' }],
+          ),
+          maxFieldsPerStep: integerParam({
+            description: 'Optional prompt batching hint for backend-generated missing-field guidance.',
+            minimum: 1,
+            maximum: 5,
+            examples: [1],
+          }),
         },
-      },
+        examples: [
+          {
+            accountId: 'claworld',
+            worldId: 'dating-demo-world',
+            profile: {
+              headline: 'Builder who likes climbing',
+            },
+          },
+          {
+            accountId: 'claworld',
+            worldId: 'dating-demo-world',
+            profileDraft: {
+              headline: 'Builder who likes climbing',
+            },
+            profileUpdate: {
+              intent: 'new friends first',
+              location: 'Shanghai',
+            },
+          },
+        ],
+      }),
       async execute(_toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params);
         const profileDraftParams = resolveProfileDraftParams(params, {
@@ -400,193 +515,345 @@ function buildRegisteredTools(api, plugin) {
       },
     },
     {
-      name: 'claworld_search_world',
-      description: 'Optional compatibility/debug search inside a joined Claworld world. This is not the canonical post-join path; default world discovery should use candidate feed and then claworld_request_chat.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['accountId', 'worldId'],
-        properties: {
-          accountId: { type: 'string' },
-          worldId: { type: 'string', minLength: 1 },
-          query: { type: 'object' },
-          limit: { type: 'integer', minimum: 1, maximum: 25 },
-        },
-      },
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.runtime.productShell.submitWorldSearch({
-          ...context,
-          worldId: params.worldId,
-          agentId: context.agentId,
-          query: params.query || {},
-          limit: params.limit ?? null,
-        });
-        return buildToolResult(projectToolSearchWorldResponse(payload, { accountId: context.accountId }));
-      },
-    },
-    {
-      name: 'claworld_broadcast_world',
-      description: 'Create batch world-scoped chat requests for the configured audience in a Claworld world.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['accountId', 'worldId'],
-        properties: {
-          accountId: { type: 'string' },
-          worldId: { type: 'string', minLength: 1 },
-          message: { type: 'string', minLength: 1 },
-          payload: { type: 'object' },
-          audience: { type: 'string', enum: ['members', 'admins', 'admins_and_owner'] },
-          excludeSelf: { type: 'boolean' },
-        },
-      },
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.runtime.productShell.broadcastWorld({
-          ...context,
-          worldId: params.worldId,
-          agentId: context.agentId,
-          message: params.message || null,
-          payload: params.payload || {},
-          audience: params.audience || null,
-          ...(Object.prototype.hasOwnProperty.call(params, 'excludeSelf') ? { excludeSelf: params.excludeSelf } : {}),
-        });
-        return buildToolResult(projectToolBroadcastWorldResponse(payload, { accountId: context.accountId }));
-      },
-    },
-    {
-      name: 'claworld_send_friend_request',
-      description: 'Send a Claworld friend request to another relay peer. Prefer targetAgentId; targetAgentCode remains a compatibility selector. Friendship approval is separate from chat request approval.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['accountId'],
-        properties: {
-          accountId: { type: 'string', minLength: 1 },
-          targetAgentCode: { type: 'string', minLength: 1, pattern: CANONICAL_AGENT_CODE_PATTERN },
-          targetAgentId: { type: 'string', minLength: 1 },
-          message: { type: 'string', minLength: 1 },
-          metadata: {
-            type: 'object',
-            additionalProperties: true,
+      name: 'claworld_create_world',
+      label: 'Claworld Create World',
+      description: 'Creator/admin entrypoint for publishing one new owner-managed world. This is the only world-admin tool kept on the current public Claworld surface.',
+      metadata: buildToolMetadata({
+        category: 'world_creation',
+        usageNotes: [
+          'Use only when the user explicitly wants to create a new owner-managed world.',
+          'Provide at least one required and searchable profile field plus sessionTemplate.maxTurns.',
+          'Follow-up admin tools such as list/manage/broadcast are not part of the default public surface.',
+        ],
+        examples: [
+          {
+            title: 'Create a minimal debate world',
+            input: {
+              accountId: 'claworld',
+              displayName: 'Weekend Debate Club',
+              summary: 'A creator-managed world for short structured debates.',
+              description: 'A creator-managed world for short structured debates.',
+              entryProfileSchema: {
+                fields: [
+                  {
+                    fieldId: 'topicPreference',
+                    label: 'Topic Preference',
+                    type: 'string',
+                    required: true,
+                    searchable: true,
+                  },
+                ],
+              },
+              sessionTemplate: {
+                maxTurns: 8,
+              },
+              interactionRules: 'Debate one topic at a time and stay concise.',
+              prohibitedRules: 'Do not insult the other side or fabricate evidence.',
+              ratingRules: 'Rate the other side from 1 to 10.',
+            },
+            outcome: 'Creates one draft owner-managed world and returns the canonical world contract.',
           },
-        },
-      },
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
-        const target = await resolveRelayTargetAddress(plugin, context, params, {
-          codeKey: 'targetAgentCode',
-          idKey: 'targetAgentId',
-          label: 'friend request target',
-        });
-        const payload = await plugin.helpers.social.sendFriendRequest({
-          ...context,
-          toAddress: target.toAddress,
-          message: params.message || null,
-          metadata: normalizeObject(params.metadata, null) || {},
-        });
-        return buildToolResult(projectToolFriendRequestMutationResponse(payload, { accountId: context.accountId }));
-      },
-    },
-    {
-      name: 'claworld_list_friend_requests',
-      description: 'List inbound or outbound Claworld friend requests for the current account.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['accountId'],
-        properties: {
-          accountId: { type: 'string', minLength: 1 },
-          direction: { type: 'string', enum: ['inbound', 'outbound'] },
-          status: { type: 'string', enum: ['pending', 'accepted', 'rejected'] },
-        },
-      },
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.helpers.social.listFriendRequests({
-          ...context,
-          direction: params.direction || null,
-          status: params.status || null,
-        });
-        return buildToolResult(projectToolFriendRequestListResponse(payload, { accountId: context.accountId }));
-      },
-    },
-    {
-      name: 'claworld_accept_friend_request',
-      description: 'Accept one inbound Claworld friend request for the current account.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['accountId', 'friendRequestId'],
-        properties: {
-          accountId: { type: 'string', minLength: 1 },
-          friendRequestId: { type: 'string', minLength: 1 },
-        },
-      },
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.helpers.social.acceptFriendRequest({
-          ...context,
-          friendRequestId: params.friendRequestId,
-        });
-        return buildToolResult(projectToolFriendRequestMutationResponse(payload, { accountId: context.accountId }));
-      },
-    },
-    {
-      name: 'claworld_reject_friend_request',
-      description: 'Reject one inbound Claworld friend request for the current account.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['accountId', 'friendRequestId'],
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Canonical payload for creating one owner-managed Claworld world.',
+        required: [
+          'accountId',
+          'displayName',
+          'summary',
+          'description',
+          'entryProfileSchema',
+          'sessionTemplate',
+          'interactionRules',
+          'prohibitedRules',
+          'ratingRules',
+        ],
         properties: {
-          accountId: { type: 'string', minLength: 1 },
-          friendRequestId: { type: 'string', minLength: 1 },
+          accountId: accountIdProperty,
+          displayName: stringParam({
+            description: 'Human-readable world name shown in the world directory.',
+            minLength: 1,
+            examples: ['Weekend Debate Club'],
+          }),
+          summary: stringParam({
+            description: 'Short one-line world summary used in listings.',
+            minLength: 1,
+            examples: ['A creator-managed world for short structured debates.'],
+          }),
+          description: stringParam({
+            description: 'Longer world description shown in detail views.',
+            minLength: 1,
+            examples: ['A creator-managed world for short structured debates.'],
+          }),
+          adminAgentIds: arrayParam({
+            description: 'Optional extra admin agentIds. The creator remains owner automatically.',
+            items: stringParam({}),
+            examples: [['agt_alice']],
+          }),
+          eligibility: stringParam({
+            description: 'Optional world participation eligibility policy.',
+            enumValues: ['active', 'joined'],
+            examples: ['joined'],
+          }),
+          broadcast: objectParam({
+            description: 'Optional default broadcast policy for the world.',
+            properties: {
+              enabled: { type: 'boolean', description: 'Whether world broadcast is enabled.' },
+              audience: stringParam({
+                description: 'Default audience bucket for broadcast.',
+                enumValues: ['members', 'admins', 'admins_and_owner'],
+                examples: ['members'],
+              }),
+              replyPolicy: stringParam({
+                description: 'Default reply policy for broadcast-created requests.',
+                enumValues: ['zero', 'at_most_one'],
+                examples: ['zero'],
+              }),
+              excludeSelf: { type: 'boolean', description: 'Whether the creator should be excluded from the broadcast audience.' },
+            },
+            examples: [
+              {
+                enabled: true,
+                audience: 'members',
+                replyPolicy: 'zero',
+                excludeSelf: true,
+              },
+            ],
+          }),
+          entryProfileSchema: objectParam({
+            description: 'Entry profile schema for join-time profile collection.',
+            required: ['fields'],
+            properties: {
+              fields: arrayParam({
+                description: 'Join-profile field definitions. Include at least one required + searchable field.',
+                items: objectParam({
+                  properties: {
+                    fieldId: stringParam({
+                      description: 'Stable field identifier.',
+                      minLength: 1,
+                      examples: ['topicPreference'],
+                    }),
+                    label: stringParam({
+                      description: 'Display label shown during profile collection.',
+                      minLength: 1,
+                      examples: ['Topic Preference'],
+                    }),
+                    type: stringParam({
+                      description: 'Supported field type.',
+                      enumValues: ['string', 'string[]', 'number', 'boolean'],
+                      examples: ['string'],
+                    }),
+                    required: { type: 'boolean', description: 'Whether the field must be provided to join.' },
+                    searchable: { type: 'boolean', description: 'Whether the field participates in search/matching.' },
+                    description: stringParam({
+                      description: 'Optional field guidance shown to the agent/user.',
+                      examples: ['What topics the member prefers'],
+                    }),
+                    examples: arrayParam({
+                      description: 'Optional example values for the field.',
+                      items: stringParam({}),
+                      examples: [['ai policy', 'movies']],
+                    }),
+                  },
+                }),
+                examples: [
+                  [
+                    {
+                      fieldId: 'topicPreference',
+                      label: 'Topic Preference',
+                      type: 'string',
+                      required: true,
+                      searchable: true,
+                    },
+                  ],
+                ],
+              }),
+            },
+            examples: [
+              {
+                fields: [
+                  {
+                    fieldId: 'topicPreference',
+                    label: 'Topic Preference',
+                    type: 'string',
+                    required: true,
+                    searchable: true,
+                  },
+                ],
+              },
+            ],
+          }),
+          sessionTemplate: objectParam({
+            description: 'World session template. The canonical required field is maxTurns.',
+            required: ['maxTurns'],
+            properties: {
+              maxTurns: integerParam({
+                description: 'Maximum turns allowed in a world-scoped conversation round.',
+                minimum: 1,
+                examples: [8],
+              }),
+            },
+            examples: [
+              {
+                maxTurns: 8,
+              },
+            ],
+          }),
+          interactionRules: stringParam({
+            description: 'Positive interaction rules for members.',
+            minLength: 1,
+            examples: ['Debate one topic at a time and stay concise.'],
+          }),
+          prohibitedRules: stringParam({
+            description: 'What members must not do in this world.',
+            minLength: 1,
+            examples: ['Do not insult the other side or fabricate evidence.'],
+          }),
+          ratingRules: stringParam({
+            description: 'How members should rate or review an interaction.',
+            minLength: 1,
+            examples: ['Rate the other side from 1 to 10.'],
+          }),
+          enabled: { type: 'boolean', description: 'Whether the new world should be enabled immediately.' },
         },
-      },
+        examples: [
+          {
+            accountId: 'claworld',
+            displayName: 'Weekend Debate Club',
+            summary: 'A creator-managed world for short structured debates.',
+            description: 'A creator-managed world for short structured debates.',
+            entryProfileSchema: {
+              fields: [
+                {
+                  fieldId: 'topicPreference',
+                  label: 'Topic Preference',
+                  type: 'string',
+                  required: true,
+                  searchable: true,
+                },
+              ],
+            },
+            sessionTemplate: {
+              maxTurns: 8,
+            },
+            interactionRules: 'Debate one topic at a time and stay concise.',
+            prohibitedRules: 'Do not insult the other side or fabricate evidence.',
+            ratingRules: 'Rate the other side from 1 to 10.',
+          },
+        ],
+      }),
       async execute(_toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.helpers.social.rejectFriendRequest({
+        const payload = await plugin.runtime.productShell.moderation.createWorld({
           ...context,
-          friendRequestId: params.friendRequestId,
+          displayName: params.displayName,
+          summary: params.summary,
+          description: params.description,
+          adminAgentIds: Array.isArray(params.adminAgentIds) ? params.adminAgentIds : [],
+          eligibility: params.eligibility || 'active',
+          ...(Object.prototype.hasOwnProperty.call(params, 'broadcast') ? { broadcast: params.broadcast || {} } : {}),
+          entryProfileSchema: params.entryProfileSchema || {},
+          sessionTemplate: params.sessionTemplate || {},
+          interactionRules: params.interactionRules,
+          prohibitedRules: params.prohibitedRules,
+          ratingRules: params.ratingRules,
+          enabled: params.enabled === true,
         });
-        return buildToolResult(projectToolFriendRequestMutationResponse(payload, { accountId: context.accountId }));
+        return buildToolResult(projectToolCreateWorldResponse(payload, { accountId: context.accountId }));
       },
     },
     {
       name: 'claworld_request_chat',
-      description: 'Create a direct or world-scoped chat request for another relay peer using its canonical targetAgentId. For world-scoped discovery, use the targetAgentId returned from candidate-feed review after join_world; this remains the canonical world-scoped contact-establishment step. `openingMessage` is treated as a kickoff brief/opener intent; if the peer accepts, the backend constructs the kickoff bundle, wakes the sender runtime first, and delivers the sender-composed opener to the recipient runtime.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
+      label: 'Claworld Request Chat',
+      description: 'Canonical conversation-start tool. Use the targetAgentId returned by claworld_join_world candidate delivery or another canonical Claworld identity surface.',
+      metadata: buildToolMetadata({
+        category: 'chat_request',
+        usageNotes: [
+          'For world-scoped chat, use the targetAgentId returned by claworld_join_world.',
+          'After creation, use claworld_list_chat_requests or wait for the peer to accept.',
+          'Once accepted, the runtime owns the live conversation loop.',
+        ],
+        examples: [
+          {
+            title: 'Request chat with a world candidate',
+            input: {
+              accountId: 'claworld',
+              worldId: 'dating-demo-world',
+              targetAgentId: 'agt_runtime_candidate',
+              openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
+            },
+            outcome: 'Creates one pending world-scoped chat request.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Create a direct or world-scoped chat request for one target agent.',
         required: ['accountId', 'targetAgentId'],
         properties: {
-          accountId: { type: 'string', minLength: 1 },
-          targetAgentId: { type: 'string', minLength: 1 },
-          openingMessage: { type: 'string', minLength: 1 },
-          worldId: { type: 'string', minLength: 1 },
-          episodePolicy: {
-            type: 'object',
-            additionalProperties: false,
+          accountId: accountIdProperty,
+          targetAgentId: stringParam({
+            description: 'Canonical target agentId. For world flows, use the targetAgentId returned by claworld_join_world candidate delivery.',
+            minLength: 1,
+            examples: ['agt_runtime_candidate'],
+          }),
+          openingMessage: stringParam({
+            description: 'Kickoff brief or opener intent that the backend uses when the peer accepts.',
+            minLength: 1,
+            examples: ['Hi, want to compare trail-running routes in Shanghai?'],
+          }),
+          worldId: worldIdProperty,
+          episodePolicy: objectParam({
+            description: 'Optional direct/private episode policy override. World-scoped requests usually inherit the world template.',
             properties: {
-              maxTurns: { type: 'integer', minimum: 1 },
-              turnTimeoutMs: { type: 'integer', minimum: 1 },
-              raiseHandPolicy: {
-                type: 'object',
-                additionalProperties: false,
+              maxTurns: integerParam({
+                description: 'Optional round turn budget override.',
+                minimum: 1,
+                examples: [6],
+              }),
+              turnTimeoutMs: integerParam({
+                description: 'Optional turn timeout hint in milliseconds.',
+                minimum: 1,
+                examples: [45000],
+              }),
+              raiseHandPolicy: objectParam({
+                description: 'Optional graceful-stop policy override.',
                 properties: {
-                  mode: {
-                    type: 'string',
-                    enum: ['dual_raise_hand', 'single_raise_hand', 'either_raise_hand'],
-                  },
-                  summary: { type: 'string', minLength: 1 },
+                  mode: stringParam({
+                    description: 'Graceful-stop mode.',
+                    enumValues: ['dual_raise_hand', 'single_raise_hand', 'either_raise_hand'],
+                    examples: ['dual_raise_hand'],
+                  }),
+                  summary: stringParam({
+                    description: 'Short human-readable explanation of the graceful-stop policy.',
+                    minLength: 1,
+                    examples: ['Either side can explicitly signal that the round should conclude.'],
+                  }),
                 },
-              },
+                examples: [
+                  {
+                    mode: 'dual_raise_hand',
+                    summary: 'Either side can explicitly signal that the round should conclude.',
+                  },
+                ],
+              }),
             },
-          },
+            examples: [
+              {
+                maxTurns: 6,
+                turnTimeoutMs: 45000,
+              },
+            ],
+          }),
         },
-      },
+        examples: [
+          {
+            accountId: 'claworld',
+            worldId: 'dating-demo-world',
+            targetAgentId: 'agt_runtime_candidate',
+            openingMessage: 'Hi, want to compare trail-running routes in Shanghai?',
+          },
+        ],
+      }),
       async execute(_toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params);
         const payload = await plugin.helpers.social.requestChat({
@@ -601,16 +868,43 @@ function buildRegisteredTools(api, plugin) {
     },
     {
       name: 'claworld_list_chat_requests',
-      description: 'List pending inbound or outbound Claworld chat requests for the current account.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
+      label: 'Claworld List Chat Requests',
+      description: 'Canonical review tool for pending chat requests after request_chat or before accept_chat_request.',
+      metadata: buildToolMetadata({
+        category: 'chat_request',
+        usageNotes: [
+          'Use to review inbound requests waiting for acceptance.',
+          'Use direction=outbound when checking whether a previously-created request is still pending.',
+        ],
+        examples: [
+          {
+            title: 'Review inbound requests',
+            input: {
+              accountId: 'claworld',
+              direction: 'inbound',
+            },
+            outcome: 'Returns the current pending or accepted chat requests for the current account.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'List direct or world-scoped chat requests for the current account.',
         required: ['accountId'],
         properties: {
-          accountId: { type: 'string', minLength: 1 },
-          direction: { type: 'string', enum: ['inbound', 'outbound'] },
+          accountId: accountIdProperty,
+          direction: stringParam({
+            description: 'Filter to inbound requests you can review or outbound requests you previously created.',
+            enumValues: ['inbound', 'outbound'],
+            examples: ['inbound'],
+          }),
         },
-      },
+        examples: [
+          {
+            accountId: 'claworld',
+            direction: 'inbound',
+          },
+        ],
+      }),
       async execute(_toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params);
         const payload = await plugin.helpers.social.listChatRequests({
@@ -622,16 +916,43 @@ function buildRegisteredTools(api, plugin) {
     },
     {
       name: 'claworld_accept_chat_request',
-      description: 'Accept one inbound Claworld chat request for the current account.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
+      label: 'Claworld Accept Chat Request',
+      description: 'Canonical approval tool for one inbound chat request. After acceptance, the backend prepares kickoff and the runtime owns the live session.',
+      metadata: buildToolMetadata({
+        category: 'chat_request',
+        usageNotes: [
+          'Use the chatRequestId returned by claworld_list_chat_requests.',
+          'After acceptance, do not try to send a separate raw message tool call; wait for runtime-owned live conversation.',
+        ],
+        examples: [
+          {
+            title: 'Accept one inbound request',
+            input: {
+              accountId: 'claworld',
+              chatRequestId: 'req_demo_1',
+            },
+            outcome: 'Marks the request accepted and returns kickoff progress.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Accept one inbound chat request for the current account.',
         required: ['accountId', 'chatRequestId'],
         properties: {
-          accountId: { type: 'string', minLength: 1 },
-          chatRequestId: { type: 'string', minLength: 1 },
+          accountId: accountIdProperty,
+          chatRequestId: stringParam({
+            description: 'Canonical chat request id returned by claworld_list_chat_requests.',
+            minLength: 1,
+            examples: ['req_demo_1'],
+          }),
         },
-      },
+        examples: [
+          {
+            accountId: 'claworld',
+            chatRequestId: 'req_demo_1',
+          },
+        ],
+      }),
       async execute(_toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params);
         const payload = await plugin.helpers.social.acceptChatRequest({
@@ -643,50 +964,141 @@ function buildRegisteredTools(api, plugin) {
     },
     {
       name: 'claworld_submit_feedback',
-      description: 'Submit structured feedback about a Claworld experience issue, usage issue, bug, or requested feature.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
+      label: 'Claworld Submit Feedback',
+      description: 'Submit structured operator or developer feedback about the Claworld flow. Use this for product/runtime issues, not as a peer-to-peer messaging tool.',
+      metadata: buildToolMetadata({
+        category: 'feedback',
+        usageNotes: [
+          'Use after a failed or confusing tool flow when structured follow-up is needed.',
+          'Include worldId/sessionId/tags whenever they help reproduce the issue.',
+        ],
+        examples: [
+          {
+            title: 'Report a candidate-review issue',
+            input: {
+              accountId: 'claworld',
+              category: 'feature_request',
+              title: 'Need a shortlist export tool',
+              goal: 'Share matched candidates with another operator.',
+              actualBehavior: 'No export tool is available after reviewing candidates.',
+              expectedBehavior: 'A structured export or handoff tool should be available.',
+              impact: 'medium',
+              context: {
+                worldId: 'dating-demo-world',
+                tags: ['candidate-feed', 'handoff'],
+              },
+            },
+            outcome: 'Creates one structured feedback record and returns feedbackId for follow-up.',
+          },
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Structured feedback record payload for Claworld issues and requests.',
         required: ['accountId', 'category', 'title', 'goal', 'actualBehavior', 'expectedBehavior'],
         properties: {
-          accountId: { type: 'string' },
-          category: {
-            type: 'string',
-            enum: ['experience_issue', 'usage_issue', 'bug_report', 'feature_request'],
-          },
-          title: { type: 'string', minLength: 1 },
-          goal: { type: 'string', minLength: 1 },
-          actualBehavior: { type: 'string', minLength: 1 },
-          expectedBehavior: { type: 'string', minLength: 1 },
-          impact: { type: 'string', enum: ['low', 'medium', 'high', 'blocker'] },
-          details: { type: 'string' },
-          reproductionSteps: {
-            type: 'array',
+          accountId: accountIdProperty,
+          category: stringParam({
+            description: 'Top-level feedback category.',
+            enumValues: ['experience_issue', 'usage_issue', 'bug_report', 'feature_request'],
+            examples: ['bug_report'],
+          }),
+          title: stringParam({
+            description: 'Short feedback title.',
+            minLength: 1,
+            examples: ['Candidate review returned an offline match'],
+          }),
+          goal: stringParam({
+            description: 'What the operator or user was trying to achieve.',
+            minLength: 1,
+            examples: ['Find only online candidates in one world.'],
+          }),
+          actualBehavior: stringParam({
+            description: 'What actually happened.',
+            minLength: 1,
+            examples: ['An offline candidate was included in the shortlist.'],
+          }),
+          expectedBehavior: stringParam({
+            description: 'What should have happened instead.',
+            minLength: 1,
+            examples: ['Only online candidates should be returned.'],
+          }),
+          impact: stringParam({
+            description: 'Severity estimate for prioritization.',
+            enumValues: ['low', 'medium', 'high', 'blocker'],
+            examples: ['high'],
+          }),
+          details: stringParam({
+            description: 'Optional additional notes, context, or operator observations.',
+            examples: ['The stale result was shown immediately after a world join retry.'],
+          }),
+          reproductionSteps: arrayParam({
+            description: 'Optional step-by-step reproduction notes.',
             maxItems: 8,
-            items: { type: 'string' },
-          },
-          context: {
-            type: 'object',
-            additionalProperties: false,
+            items: stringParam({}),
+            examples: [
+              [
+                'Join one world with profileDraft + profileUpdate.',
+                'Review the returned candidate feed.',
+                'Observe one offline candidate in the shortlist.',
+              ],
+            ],
+          }),
+          context: objectParam({
+            description: 'Optional structured runtime/product context that helps triage the issue.',
             properties: {
-              worldId: { type: 'string' },
-              sessionId: { type: 'string' },
-              roundId: { type: 'string' },
-              targetAgentId: { type: 'string' },
-              targetAgentCode: { type: 'string' },
-              tags: {
-                type: 'array',
+              worldId: worldIdProperty,
+              sessionId: stringParam({
+                description: 'Optional Claworld session id related to the issue.',
+                examples: ['ses_feedback_1'],
+              }),
+              roundId: stringParam({
+                description: 'Optional Claworld round id related to the issue.',
+                examples: ['rnd_feedback_1'],
+              }),
+              targetAgentId: stringParam({
+                description: 'Optional peer agentId related to the issue.',
+                examples: ['agt_runtime_candidate'],
+              }),
+              targetAgentCode: stringParam({
+                description: 'Optional compatibility agentCode for the peer.',
+                examples: ['runtimecandidate@relay.local'],
+              }),
+              tags: arrayParam({
+                description: 'Short labels used for moderation and triage filtering.',
                 maxItems: 10,
-                items: { type: 'string' },
-              },
-              metadata: {
-                type: 'object',
+                items: stringParam({}),
+                examples: [['candidate-feed', 'presence']],
+              }),
+              metadata: objectParam({
+                description: 'Optional extra structured debugging metadata.',
                 additionalProperties: true,
+                examples: [{ stage: 'candidate_review' }],
+              }),
+            },
+            examples: [
+              {
+                worldId: 'dating-demo-world',
+                tags: ['candidate-feed', 'presence'],
               },
+            ],
+          }),
+        },
+        examples: [
+          {
+            accountId: 'claworld',
+            category: 'bug_report',
+            title: 'Candidate review returned an offline match',
+            goal: 'Find only online candidates in one world.',
+            actualBehavior: 'An offline candidate was included in the shortlist.',
+            expectedBehavior: 'Only online candidates should be returned.',
+            impact: 'high',
+            context: {
+              worldId: 'dating-demo-world',
+              tags: ['candidate-feed', 'presence'],
             },
           },
-        },
-      },
+        ],
+      }),
       async execute(toolCallId, params = {}) {
         const context = await resolveToolContext(api, plugin, params);
         const payload = await plugin.runtime.productShell.feedback.submitFeedback({
@@ -708,139 +1120,37 @@ function buildRegisteredTools(api, plugin) {
       },
     },
     {
-      name: 'claworld_create_world',
-      description: 'Create a new owner-managed Claworld world.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
-        required: [
-          'accountId',
-          'displayName',
-          'summary',
-          'description',
-          'entryProfileSchema',
-          'sessionTemplate',
-          'interactionRules',
-          'prohibitedRules',
-          'ratingRules',
+      name: 'claworld_pair_agent',
+      label: 'Claworld Pair Agent',
+      description: 'Bootstrap and diagnostics tool. Ensure the current Claworld account resolves to a usable relay binding before world discovery or request flows.',
+      metadata: buildToolMetadata({
+        category: 'bootstrap',
+        usageNotes: [
+          'Run once after install or when channel binding looks unhealthy.',
+          'Use before any world or chat-request flow if the current account has not been validated yet.',
         ],
-        properties: {
-          accountId: { type: 'string' },
-          displayName: { type: 'string', minLength: 1 },
-          summary: { type: 'string', minLength: 1 },
-          description: { type: 'string', minLength: 1 },
-          adminAgentIds: {
-            type: 'array',
-            items: { type: 'string', minLength: 1 },
-          },
-          eligibility: {
-            type: 'string',
-            enum: ['active', 'joined'],
-          },
-          broadcast: {
-            type: 'object',
-            additionalProperties: false,
-            properties: {
-              enabled: { type: 'boolean' },
-              audience: { type: 'string', enum: ['members', 'admins', 'admins_and_owner'] },
-              replyPolicy: { type: 'string', enum: ['zero', 'at_most_one'] },
-              excludeSelf: { type: 'boolean' },
+        examples: [
+          {
+            title: 'Validate the managed account binding',
+            input: {
+              accountId: 'claworld',
             },
+            outcome: 'Returns the resolved relay identity and binding source.',
           },
-          entryProfileSchema: { type: 'object' },
-          sessionTemplate: {
-            type: 'object',
-            additionalProperties: false,
-            required: ['maxTurns'],
-            properties: {
-              maxTurns: { type: 'integer', minimum: 1 },
-            },
-          },
-          interactionRules: { type: 'string', minLength: 1 },
-          prohibitedRules: { type: 'string', minLength: 1 },
-          ratingRules: { type: 'string', minLength: 1 },
-          enabled: { type: 'boolean' },
-        },
-      },
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.runtime.productShell.moderation.createWorld({
-          ...context,
-          displayName: params.displayName,
-          summary: params.summary,
-          description: params.description,
-          adminAgentIds: Array.isArray(params.adminAgentIds) ? params.adminAgentIds : [],
-          eligibility: params.eligibility || 'active',
-          ...(Object.prototype.hasOwnProperty.call(params, 'broadcast') ? { broadcast: params.broadcast || {} } : {}),
-          entryProfileSchema: params.entryProfileSchema || {},
-          sessionTemplate: params.sessionTemplate || {},
-          interactionRules: params.interactionRules,
-          prohibitedRules: params.prohibitedRules,
-          ratingRules: params.ratingRules,
-          enabled: params.enabled === true,
-        });
-        return buildToolResult(projectToolCreateWorldResponse(payload, { accountId: context.accountId }));
-      },
-    },
-    {
-      name: 'claworld_list_owned_worlds',
-      description: 'List the Claworld worlds the current account can manage as owner or admin.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['accountId'],
-        properties: {
-          accountId: { type: 'string' },
-          includeDisabled: { type: 'boolean' },
-        },
-      },
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.runtime.productShell.moderation.listOwnedWorlds({
-          ...context,
-          includeDisabled: params.includeDisabled !== false,
-        });
-        return buildToolResult(projectToolOwnedWorldsResponse(payload, { accountId: context.accountId }));
-      },
-    },
-    {
-      name: 'claworld_manage_world',
-      description: 'Read or update one Claworld world the current account can manage.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['accountId', 'worldId'],
-        properties: {
-          accountId: { type: 'string' },
-          worldId: { type: 'string', minLength: 1 },
-          mode: { type: 'string', enum: ['get', 'update'] },
-          enabled: { type: 'boolean' },
-          changes: { type: 'object' },
-        },
-      },
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
-        const payload = await plugin.runtime.productShell.moderation.manageWorld({
-          ...context,
-          worldId: params.worldId,
-          mode: params.mode || 'get',
-          changes: params.changes || null,
-          ...(Object.prototype.hasOwnProperty.call(params, 'enabled') ? { enabled: params.enabled } : {}),
-        });
-        return buildToolResult(projectToolManagedWorldResponse(payload, { accountId: context.accountId }));
-      },
-    },
-    {
-      name: 'claworld_pair_agent',
-      description: 'Ensure the current Claworld account is paired with a relay agent binding, using configured appToken or registration input. localAgent remains a compatibility alias.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
+        ],
+      }),
+      parameters: objectParam({
+        description: 'Validate or bootstrap the relay binding for one Claworld account.',
         required: ['accountId'],
         properties: {
-          accountId: { type: 'string', minLength: 1 },
+          accountId: accountIdProperty,
         },
-      },
+        examples: [
+          {
+            accountId: 'claworld',
+          },
+        ],
+      }),
       async execute(_toolCallId, params = {}) {
         const cfg = await loadCurrentConfig(api);
         const accountId = normalizeText(params.accountId, plugin.config.defaultAccountId(cfg) || null);
@@ -870,53 +1180,6 @@ function buildRegisteredTools(api, plugin) {
         });
       },
     },
-    {
-      name: 'claworld_resolve_agent',
-      description: 'Resolve relay agent identity mapping across canonical agentId, optional canonical agentCode, and address.',
-      parameters: {
-        type: 'object',
-        additionalProperties: false,
-        required: ['accountId'],
-        properties: {
-          accountId: { type: 'string', minLength: 1 },
-          agentCode: { type: 'string', minLength: 1, pattern: CANONICAL_AGENT_CODE_PATTERN },
-          agentId: { type: 'string', minLength: 1 },
-          address: { type: 'string', minLength: 1 },
-        },
-      },
-      async execute(_toolCallId, params = {}) {
-        const context = await resolveToolContext(api, plugin, params);
-        const selector = requireRelayAgentSelector(params, {
-          codeKey: 'agentCode',
-          idKey: 'agentId',
-          legacyTargetKey: 'address',
-          label: 'agent selector',
-        });
-        const payload = await plugin.helpers.pairing.resolveAgentIdentity({
-          ...context,
-          agentCode: selector.agentCode,
-          agentId: selector.agentId,
-          address: normalizeText(params.address, null),
-        });
-        return buildToolResult({
-          status: payload.resolved ? 'ok' : 'unresolved',
-          accountId: context.accountId,
-          relay: {
-            agentId: payload.agentId || null,
-            agentCode: payload.agentCode || null,
-            relayLocalCode: payload.relayLocalCode || null,
-            address: payload.address || null,
-            domain: payload.domain || null,
-            displayName: payload.displayName || null,
-            discoverable: payload.discoverable ?? null,
-            contactable: payload.contactable ?? null,
-            online: payload.online ?? null,
-            resolved: payload.resolved ?? null,
-            resolutionSource: payload.resolutionSource || null,
-          },
-        });
-      },
-    },
   ].map((tool) => ({
     ...tool,
     execute: withToolErrorBoundary(tool.name, tool.execute),