random_shuffleShuffle a list into a uniformly random order with Fisher-Yates over the platform CSPRNG. Every permutation is equally likely, which sorting by a random key does not give you. $0.005 per call, paid over x402 (USDC).
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | The list to shuffle, comma-separated. A JSON array of strings is also accepted in a POST body. |
Changes observed during successful MCP inspections.
Input schema / properties / items / descriptionPrevious value: -"The list to shuffle. In a GET, comma-separated."New value: +"The list to shuffle, comma-separated. A JSON array of strings is also accepted in a POST body."Input schema / properties / items / typePrevious value: -"array"New value: +"string"Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the important operational traits: the randomness source (platform CSPRNG), the uniformity guarantee, and the billing model ($0.005 per call paid over x402 in USDC). What it omits is the return shape and edge-case behavior (empty list, single item), which matters for a paid call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with the core action, then the differentiator, then the cost. Each sentence earns its place: the Fisher-Yates/random-key comparison justifies the implementation choice and the price disclosure is essential for a paid tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with 100% schema coverage but no output schema and no annotations, the description covers purpose, guarantee, and cost adequately. It stops short of stating what is returned or how degenerate inputs are handled, which would complete the picture for a non-deterministic paid operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'items' parameter, and the schema already documents both the comma-separated form and the JSON-array POST body alternative. The description adds no further meaning about the parameter, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('shuffle a list into a uniformly random order') and pins down the algorithm (Fisher-Yates over the platform CSPRNG), which clearly separates it from siblings like random_pick, random_number, and random_dice. An agent can tell immediately that this permutes an entire list rather than drawing a value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the shuffle semantics, and the description contrasts against a naive 'sort by random key' approach, but that is a correctness argument rather than routing guidance. It never says when to choose this over random_pick (one element) or when shuffling is inappropriate, and no explicit prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.