Skip to main content
Glama

Make balanced groups

make_groups
Read-onlyIdempotent

Split people into balanced groups with a MILP solver and return each group's members, a per-group summary of every field, the overall mix, a balance score per field (100 = perfectly balanced), notes and warnings. Give groups (a number of groups; sizes then differ by at most 1) OR min_size and/or max_size (the server tries every group count that fits and picks the best); with both, groups decides and the sizes only validate it. priorities maps a field to 1 (most important), 2, 3...; a field left out counts least; equal numbers tie. Solves take up to about 20 s. If the result has status 'running', call get_group_result with its job_id. If it has status 'busy', wait the retry_after_seconds it gives and call again -- one call at a time, never in parallel. If it has status 'error' or 'infeasible', the message says in plain words what to change. Defaults applied (e.g. a field with no priority) are listed in assumptions; tell the user about them. Call get_group_example for a complete, realistic input.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "make_groups"
  }
}

Input Schema

NameRequiredDescriptionDefault
goalNoOne sentence, in the user's own words, of what they are trying to do (e.g. 'six mixed-ability reading groups for my class'). Optional; helps improve the tool. Do not put names in it.
groupsNoNumber of groups (max 60).
peopleNoThe people to group (2-300).
max_sizeNoLargest allowed group size.
min_sizeNoSmallest allowed group size.
prioritiesNoField name -> priority number (1 = most important). Each step is worth 4x the next; a field with no priority counts least.
wait_secondsNoHow long to wait for the solve inside this call (default 25).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnly/idempotent annotations by disclosing that solves can take ~20 s, that the call may return status 'running' or 'busy', that only one call may be in flight at a time ('never in parallel'), and that defaults surface in `assumptions` which must be relayed to the user. Missing only detail on how long job results persist or how the balance score is computed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose and return shape, then handles sizing, priorities, and status branches in a logical order. Some sentences are dense and long ('Solves take up to about 20 s.' sits mid-paragraph), but essentially every clause carries operational information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by enumerating the return payload (members, per-group summary, overall mix, balance score, notes/warnings). Combined with the async status protocol and the pointer to get_group_example, an agent has everything needed for a complex 7-parameter nested-schema tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning the schema lacks: the precedence of `groups` over size bounds ('the sizes only validate it'), and how `priorities` works ('a field left out counts least; equal numbers tie'). It does not restate the obviously documented nested fields.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Split people into balanced groups') plus the method (MILP solver) and the exact return payload, so the agent knows both what it does and what comes back. The status-handling sentences further separate it from get_group_result and get_group_example.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the two ways to size groups ('Give `groups` ... OR `min_size` and/or `max_size`') and the precedence rule when both are supplied. It also routes the agent: call get_group_result on status 'running', retry on 'busy', and read the message on 'error'/'infeasible'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources