read.strategy.recommendation

Instructions

Implementation Reference

• src/tools/read/strategy.ts:162-212 (registration)

  Registration of the 'read.strategy.recommendation' tool on the MCP server with annotations, description, input schema, and handler.

  server.registerTool(
    "read.strategy.recommendation",
    {
      annotations: {
        title: "Get Recommendation",
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: true,
      },
      description:
        "Get a rebalancing recommendation for an Arcadia account — suggests asset changes to optimize yield. Uses 1d APY (not 7d like read.strategy.list), so recommended strategies may differ from the list ranking. APY values are decimal fractions (0.05 = 5%). weekly_earning_difference is in USD.",
      inputSchema: {
        account_address: z.string().describe("Arcadia account address"),
        chain_id: z.number().default(8453).describe(CHAIN_ID_DESCRIPTION),
      },
      outputSchema: StrategyRecommendationOutput,
    },
    async ({ account_address, chain_id }) => {
      try {
        const result = await api.getRecommendation(chain_id, account_address);
        const rec = result as Record<string, unknown>;
        if (
          Array.isArray(rec.added_assets) &&
          rec.added_assets.length === 0 &&
          Array.isArray(rec.removed_assets) &&
          rec.removed_assets.length === 0 &&
          Number(rec.current_apy ?? 0) === 0 &&
          Number(rec.proposed_apy ?? 0) === 0
        ) {
          rec.context_notes = [
            "Account has no active positions — no rebalancing recommendations available.",
          ];
        }
        return {
          content: [{ type: "text" as const, text: JSON.stringify(rec, null, 2) }],
          structuredContent: rec,
        };
      } catch (err) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error: ${err instanceof Error ? err.message : String(err)}`,
            },
          ],
          isError: true,
        };
      }
    },
  );

• src/tools/read/strategy.ts:180-211 (handler)

  Handler function for read.strategy.recommendation: calls api.getRecommendation(chain_id, account_address), checks if result has no positions (empty added/removed assets and zero APYs) to add context_notes, returns JSON-stringified result with structuredContent.

  async ({ account_address, chain_id }) => {
    try {
      const result = await api.getRecommendation(chain_id, account_address);
      const rec = result as Record<string, unknown>;
      if (
        Array.isArray(rec.added_assets) &&
        rec.added_assets.length === 0 &&
        Array.isArray(rec.removed_assets) &&
        rec.removed_assets.length === 0 &&
        Number(rec.current_apy ?? 0) === 0 &&
        Number(rec.proposed_apy ?? 0) === 0
      ) {
        rec.context_notes = [
          "Account has no active positions — no rebalancing recommendations available.",
        ];
      }
      return {
        content: [{ type: "text" as const, text: JSON.stringify(rec, null, 2) }],
        structuredContent: rec,
      };
    } catch (err) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error: ${err instanceof Error ? err.message : String(err)}`,
          },
        ],
        isError: true,
      };
    }
  },

• src/tools/output-schemas.ts:147-147 (schema)

  Output schema StrategyRecommendationOutput — a passthrough empty object schema allowing any shape.

  export const StrategyRecommendationOutput = z.object({}).passthrough();

• src/clients/api.ts:192-196 (helper)

  ArcadiaApiClient.getRecommendation method — fetches GET /recommendation with chain_id and account parameters from the Arcadia API.

  // ── Recommendation ───────────────────────────────────────────────
  
  async getRecommendation(chainId: number, account: string) {
    return this.get("/recommendation", { chain_id: chainId, account });
  }

• src/prompts/workflows.ts:28-28 (helper)

  References read.strategy.recommendation in the 'analyze-account' workflow prompt, instructing the model to call it as step 4.

  "4. Call read.strategy.recommendation to check if rebalancing is needed",