convert_scores

Instructions

Implementation Reference

• src/index.ts:868-907 (registration)

  Registration of the 'convert_scores' tool via server.tool() with the name 'convert_scores'.

  server.tool(
    "convert_scores",
    "Convert between probability floats (0.0–1.0) and Q0.16 fixed-point integers (0–65535) — no API call, no auth, no credits. Response: { direction, count, converted: [{ input, q16|float }] }. Use to_q16 before evaluate, from_q16 to make CI outputs human-readable.",
    {
      scores: z.array(z.number()).min(1).max(300).describe("Array of scores to convert"),
      direction: z.enum(["to_q16", "from_q16"]).describe('"to_q16" converts 0.0–1.0 floats to Q0.16 integers. "from_q16" converts Q0.16 integers to floats.'),
    },
    async ({ scores, direction }) => {
      if (direction === "to_q16") {
        const converted = scores.map((s) => {
          const clamped = Math.max(0, Math.min(1, s));
          const q16 = Math.round(clamped * Q16);
          return { input: s, q16, clamped: s !== clamped };
        });
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({ direction, count: scores.length, converted }, null, 2),
            },
          ],
        };
      }
  
      // from_q16
      const converted = scores.map((s) => {
        const clamped = Math.max(0, Math.min(Q16, Math.round(s)));
        const float_val = Number((clamped / Q16).toFixed(6));
        return { input: s, float: float_val };
      });
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({ direction, count: scores.length, converted }, null, 2),
          },
        ],
      };
    }
  );

• src/index.ts:871-874 (schema)

  Zod input schema for convert_scores: 'scores' (array of numbers, 1-300) and 'direction' (enum: 'to_q16' or 'from_q16').

  {
    scores: z.array(z.number()).min(1).max(300).describe("Array of scores to convert"),
    direction: z.enum(["to_q16", "from_q16"]).describe('"to_q16" converts 0.0–1.0 floats to Q0.16 integers. "from_q16" converts Q0.16 integers to floats.'),
  },

• src/index.ts:875-907 (handler)

  Handler function implementing the conversion logic. For 'to_q16': clamps input 0-1 and multiplies by 65535. For 'from_q16': clamps to 0-65535 and divides by 65535, returning a 6-decimal float.

    async ({ scores, direction }) => {
      if (direction === "to_q16") {
        const converted = scores.map((s) => {
          const clamped = Math.max(0, Math.min(1, s));
          const q16 = Math.round(clamped * Q16);
          return { input: s, q16, clamped: s !== clamped };
        });
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({ direction, count: scores.length, converted }, null, 2),
            },
          ],
        };
      }
  
      // from_q16
      const converted = scores.map((s) => {
        const clamped = Math.max(0, Math.min(Q16, Math.round(s)));
        const float_val = Number((clamped / Q16).toFixed(6));
        return { input: s, float: float_val };
      });
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({ direction, count: scores.length, converted }, null, 2),
          },
        ],
      };
    }
  );

• src/index.ts:296-304 (helper)

  Helper function 'toQ16' used by other tools (evaluate, fleet_evaluate, interpret_scores) to auto-convert float scores to Q0.16. This is a supporting helper but not directly used by convert_scores itself.

  /** Auto-convert: if all values are 0–1 floats with decimals, scale to Q0.16. Otherwise clamp to 0–65535. */
  function toQ16(scores: number[]): number[] {
    const hasDecimals = scores.some((s) => s % 1 !== 0);
    const allInUnit = scores.every((s) => s >= 0 && s <= 1);
    const isFloat = hasDecimals && allInUnit;
    return isFloat
      ? scores.map((s) => Math.round(Math.max(0, Math.min(1, s)) * Q16))
      : scores.map((s) => Math.round(Math.max(0, Math.min(Q16, s))));
  }

• src/index.ts:242-243 (helper)

  Constant Q16 = 65535 used for Q0.16 fixed-point conversion in the convert_scores handler and throughout the codebase.

  const Q16 = 65535;