Tools for agents: Exact weighted integer allocation

Divide indivisible units proportionally using exact quotas, largest remainders and transparent tie handling.

Connect with MCP

{
  "mcpServers": {
    "super-agent-tools": {
      "url": "https://app.getsupers.com/sites/agent-weighted-allocation/mcp"
    }
  }
}
Streamable HTTP · No API key · Stateless

Use this URL in any client supporting remote Streamable HTTP MCP. Calls return structured JSON; inputs are processed without persistence.

Call allocate_weighted_units

Uses the largest-remainder method: compute each exact proportional quota, allocate its floor, then award remaining units to the largest fractional remainders. Equal remainders are resolved by recipient input order; reorder intentionally if a different tie priority is desired. Returns recipients in input order and exposes the complete remainder priority order. Weights must be nonnegative with positive total weight; zero-weight recipients receive zero. total is a nonnegative JSON integer. Weights accept integers or quoted decimal/fraction strings; floats and booleans are rejected. Allocations sum exactly to total. No capacity constraints, minimum allocations, random tie-breaking or scheduling are applied. Increasing total can reduce an individual allocation under this method; it is not a monotone allocation rule. This calculates a plan without assigning resources or persisting state.

Input and output schemas
{
  "name": "allocate_weighted_units",
  "title": "Exact weighted integer allocation",
  "description": "Allocate a nonnegative integer total by exact largest remainders. Equal remainders are resolved by recipient input order, with that ordering exposed in the result.",
  "inputSchema": {
    "$defs": {
      "Recipient": {
        "properties": {
          "id": {
            "minLength": 1,
            "title": "Id",
            "type": "string"
          },
          "weight": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "string"
              }
            ],
            "title": "Weight"
          }
        },
        "required": [
          "id",
          "weight"
        ],
        "title": "Recipient",
        "type": "object"
      }
    },
    "properties": {
      "total": {
        "title": "Total",
        "type": "integer"
      },
      "recipients": {
        "items": {
          "$ref": "#/$defs/Recipient"
        },
        "title": "Recipients",
        "type": "array"
      }
    },
    "required": [
      "total",
      "recipients"
    ],
    "title": "allocate_weighted_unitsArguments",
    "type": "object"
  },
  "outputSchema": {
    "additionalProperties": true,
    "title": "allocate_weighted_unitsDictOutput",
    "type": "object"
  },
  "icons": null,
  "annotations": {
    "title": null,
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "meta": null,
  "execution": null
}

Run the example to see the actual result.

HTTP alternative

POST https://app.getsupers.com/sites/agent-weighted-allocation/call
Content-Type: application/json

{
  "total": 10,
  "recipients": [
    {
      "id": "research",
      "weight": 5
    },
    {
      "id": "build",
      "weight": 3
    },
    {
      "id": "verify",
      "weight": 2
    }
  ]
}

The HTTP and MCP interfaces execute the same implementation. Validation errors are returned explicitly. See the tool notes above for its supported inputs and behavior.

Exact quotas and remainders allocate indivisible units

Read the explanation

The saved example divides ten indivisible units using weights five for research, three for build and two for verify. Total weight is ten, so exact quotas are five, three and two. Floors already sum to ten; no remainder award is needed. This returns an allocation plan and does not assign resources or schedule workers. The offline preview does not call the remote implementation. For a worked variation with the same weights and seven total units, exact quotas are three point five, two point one and one point four. Floors are three, two and one, totaling six. One unit remains. Fractional remainders rank research point five, verify point four, then build point one. Research receives the extra unit; final allocations are four, two and one, summing exactly to seven. Equal remainders are resolved by recipient input order. Splitting one unit between two equal weights produces a half quota for each; the first recipient receives the indivisible unit. The full priority order is exposed. Weights must be nonnegative with positive total, and zero weights receive zero. Exact inputs use integers or quoted decimals or fractions. The method has no capacity constraints or random tie breaker, and increasing total can reduce one allocation in some cases.

Exact Weighted Integer Allocation with the Largest-Remainder Method

How does the largest-remainder method divide indivisible integer units according to recipient weights?

When allocating indivisible integer units according to arbitrary weights, exact proportional shares (quotas) are almost always fractional. The largest-remainder method (historically known as Hamilton's method) calculates each recipient's exact quota, allocates the integer floor of that quota, and then distributes the remaining units one-by-one to recipients with the largest fractional remainders.

Largest-remainder allocation is stateless and calculates a proportional distribution without enforcing minimum quotas, maximum capacity ceilings, or sequential scheduling. It is also subject to the quota paradoxes (such as the Alabama paradox), where increasing the total number of units to allocate can cause a recipient's allocated count to decrease.

Try a worked example

With total = 10 and weights research: 5, build: 3, verify: 2, total weight is 10. The exact quotas are 10 × 5/10 = 5.0, 10 × 3/10 = 3.0, and 10 × 2/10 = 2.0. Their floors sum to 5 + 3 + 2 = 10, leaving 0 extra units. Clicking 'Run tool' executes the endpoint and returns allocated: 5 for research, 3 for build, and 2 for verify with no extra remainder awards.

Quota Calculation and Floor Allocation

For each recipient i with weight w_i, the exact fractional quota is calculated as total * (w_i / sum(weights)). The algorithm first assigns floor(quota_i) units to each recipient. Because each quota is rounded down, the sum of these floors is less than or equal to total.

Remainder Prioritization and Deterministic Tie-Breaking

The difference between total and the sum of the floor allocations defines the number of leftover units (k). Each recipient has a fractional remainder quota_i - floor(quota_i). Leftover units are awarded to the recipients with the k largest fractional remainders. When two remainders are identical, this implementation breaks ties deterministically based on input order.