# Request a Tool

> Ask for a new deterministic tool. Agents can request tools for themselves over the API, MCP or A2A.

Category: Requests · Page: https://util.caruana.me/tools/request/

## API, MCP and A2A

### Request a new tool (`tool_request`)

`GET|POST https://util.caruana.me/api/tools/request` · MCP tool `tool_request` · A2A skill `tool_request` · [reference](https://util.caruana.me/reference/tool_request/)

Records a request for a new tool. Use it when you (an agent or a person) keep doing the same deterministic job that has exactly one right answer and no tool here does it: a conversion, a validation, a calculation, a parser. Describe the job in `problem`, and give an `example_input` and the `expected_output` if you can; concrete examples make a request much more likely to be built. Requests are reviewed by the owner; check progress with `tool_requests`. A request is a suggestion, not an order, and nothing is guaranteed. Each client can submit up to 20 requests per 24 hours.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string (≤ 120 chars) | yes | Short name for the tool, e.g. "IBAN validator" or "Semantic version compare". |
| `problem` | string (≤ 4000 chars) | yes | What you need done, why, and how you do it today. Say if you are an agent and what you are working on. |
| `example_input` | string (≤ 4000 chars) | no | A sample input the tool would receive (no secrets or personal data). |
| `expected_output` | string (≤ 4000 chars) | no | What the tool should return for `example_input`. |
| `category` | Encoding \| Hashing \| Keys & Certificates \| Inspect & Identify \| Text & Data \| Time & Scheduling \| Other | no | Closest existing category, or `Other`. |

Privacy: Unlike the other operations, the server stores what you send here (title, problem, examples and category), with your client ID and the time, so the request can be reviewed and answered. It is not shared with other clients, except that a request marked planned, building or shipped may appear by title as related to similar requests. Do not include secrets or personal data. Only the per-call metadata row is logged.

### List your tool requests (`tool_requests`)

`GET|POST https://util.caruana.me/api/tools/requests` · MCP tool `tool_requests` · A2A skill `tool_requests` · [reference](https://util.caruana.me/reference/tool_requests/)

Returns every tool request made with your client ID, newest first, with its current status and the owner's note. When a request is `shipped`, `shipped_url` points at the new tool. Requests made through the web form are not linked to a client and do not appear here.

No parameters.

Privacy: The server reads the tool requests stored under your client ID and returns them. Nothing you send is stored.


## User guide

The tool sits in a window that works like a desktop app: menus on the top row and the **full-screen** icon at its right (**Esc** leaves full screen). **Help → Keyboard shortcuts…** lists the keys.

This toolbox grows by request. If you, or an agent you run, keep doing the same deterministic job by hand (a conversion, a check, a calculation, a parser with exactly one right answer), ask for it here.

1. **Name the tool**, e.g. _IBAN validator_ or _Semantic version compare_.
2. **Say what it should do**: the job, why you need it, and how you do it today.
3. **Give an example** input and the output you expect. Concrete examples are the single best way to get a tool built: they become its first test.
4. Optionally leave an **email** for a reply, then press **Send request** (or **File → Send request**).

You get a reference (`tr_…`). If a similar request is already planned, building or shipped, it is listed, and a shipped one may already do the job.

**For agents.** Agents can ask for tools for themselves, with their own credentials (which agents can [register for](/reference/auth/) without a person):

- HTTP: `POST /api/tools/request` with `title`, `problem`, and optionally `example_input`, `expected_output` and `category`. `GET /api/tools/requests` lists your requests and their status.
- MCP: the tools `tool_request` and `tool_requests`.
- A2A: the skills `tool_request` and `tool_requests`.

A good moment to call `tool_request` is when you notice you are reasoning your way through something a function should answer.

## Specification

**What happens to a request.** Each one is read by the owner and gets a status: `received` (not reviewed yet), `planned`, `building`, `shipped` (with the tool's URL), `declined` or `duplicate`, often with a short note. Agents see these through `tool_requests`. Form requests are not linked to an identity, so the only follow-up is by the email you leave, if any.

**What makes a good tool here.** Deterministic (same input, same output), useful to more than one caller, and safe to run without secrets. Tools that would need to store your data, accept private keys or passwords, or act on other systems are declined: see [Security & privacy](/security/).

**Limits.** Title up to 120 characters; description and each example up to 4,000. Each API client can make 20 requests per 24 hours. The form needs the Turnstile check to pass.

**Related requests.** When you submit, titles of _accepted_ requests (planned, building or shipped) that share words with yours are returned, without who asked for them. Requests that are only received, or declined, are never shown to anyone else.