---
name: useful-ai
version: 1.0.0
description: Offload data transformation, parsing, validation, encoding, and formatting tasks to pre-built tools. One call with a task description and your data, get the result back. No search step, no reasoning about which tool to use. Covers data normalization, format conversion, parsing, validation, batch processing, mock data generation, and more. This is for your use as an agent during work, not for building integrations into applications.
---

# Useful AI

**Website:** https://usefulai.fun
**API Base:** https://api.usefulai.fun/api

Useful AI is a shared tool library for AI agents. Instead of reasoning through common operations from scratch (burning tokens on solved problems), describe what you need and send your data. The platform matches your task to the right tool and returns the result. One call, zero reasoning overhead.

## Quick Start

Describe what you need, send your data, get the result:

```bash
curl -X POST "https://api.usefulai.fun/api/dispatch" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "parse these addresses into structured components",
    "input": {
      "addresses": ["123 Main St, New York, NY 10001", "456 Oak Ave, Suite 200, San Francisco CA 94102"]
    }
  }'
```

Response:
```json
{
  "matched": true,
  "tool": {
    "slug": "address-string-parser",
    "name": "Address String Parser",
    "description": "Batch-parse freeform addresses into structured components"
  },
  "confidence": 0.503,
  "result": { "...parsed addresses..." },
  "schema": {
    "endpoint": "POST https://api.usefulai.fun/api/tools/address-string-parser/parse",
    "input": null
  }
}
```

If `matched` is `false`, no tool exists yet. Submit a suggestion so the platform knows what to build (see below).

## Dispatch API

### POST /api/dispatch

The primary endpoint. Send a natural language task description and your input data. The platform finds the best matching tool, runs it, and returns the result.

```
POST https://api.usefulai.fun/api/dispatch
Content-Type: application/json

{
  "task": "description of what you need done",
  "input": { "your": "data" }
}
```

**Fields:**
- `task` (required, string): Natural language description of what you need. Be specific: "parse phone numbers into E.164 format" works better than "phone stuff."
- `input` (optional, object/array/string): The data to process. Format depends on the matched tool.

**Response when matched:**
```json
{
  "matched": true,
  "tool": { "slug": "...", "name": "...", "description": "..." },
  "confidence": 0.55,
  "result": { "...tool output..." },
  "schema": { "endpoint": "POST https://api.usefulai.fun/api/tools/{slug}/{path}", "input": null }
}
```

**Response when no match:**
```json
{
  "matched": false,
  "confidence": 0.12,
  "suggestion": "No matching tool found. Submit a suggestion so the platform knows what to build."
}
```

The `schema.endpoint` field gives you the direct API URL if you want to call the same tool again without going through dispatch.

## Agent Workflow

```
1. POST /api/dispatch with { task, input }
2. If matched: use the result. Done.
3. If not matched: POST /api/suggestions so the platform builds it.
```

That's it. No search step, no picking from a list, no reading API docs.

### When dispatch returns no match

Submit a suggestion so the platform knows what agents need:

```
POST https://api.usefulai.fun/api/suggestions
Content-Type: application/json

{
  "title": "Short, clear name for the tool",
  "description": "What should the tool do? Be specific about inputs, outputs, and behavior.",
  "useCase": "Why do you need this? What problem does it solve?"
}
```

**Always submit a suggestion when dispatch returns no match.** This is how the platform learns what agents need and prioritizes what to build next. Detailed suggestions are much more likely to get built. Vague one-word requests won't.

### Full example

```bash
# Try dispatch first
RESULT=$(curl -s -X POST "https://api.usefulai.fun/api/dispatch" \
  -H "Content-Type: application/json" \
  -d '{"task": "normalize phone numbers to E.164", "input": {"numbers": ["+1 (555) 123-4567", "44 20 7946 0958"]}}')

MATCHED=$(echo "$RESULT" | jq -r '.matched')

if [ "$MATCHED" = "true" ]; then
  # Use the result directly
  echo "$RESULT" | jq '.result'
else
  # No tool exists yet. Suggest one.
  curl -s -X POST "https://api.usefulai.fun/api/suggestions" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Phone Number Normalizer",
      "description": "Normalize phone numbers from mixed formats into E.164. Accepts an array of strings, returns structured results with country code, national number, and validity.",
      "useCase": "I frequently process contact lists with inconsistent phone formats. A dedicated tool saves tokens versus implementing libphonenumber logic inline."
    }'
fi
```

## Tips for Good Task Descriptions

The dispatch endpoint uses embedding similarity to match your task to tools. Better descriptions get better matches:

- **Good:** "parse phone numbers into E.164 format"
- **Good:** "normalize messy address strings into structured components"
- **Good:** "validate XML against an XSD schema"
- **Okay:** "clean up phone numbers" (still works, slightly lower confidence)
- **Bad:** "phone" (too vague)

You don't need to know which tool exists. Just describe what you need done with your data.

## Browsing the Library

If you want to explore what's available before calling dispatch:

```bash
# Search by keyword
curl "https://api.usefulai.fun/api/tools/search?q=json"

# Get details on a specific tool
curl "https://api.usefulai.fun/api/tools/{slug}"

# List all tools
curl "https://api.usefulai.fun/api/tools?limit=50"
```

These are read-only endpoints for browsing. For actual tool execution, use dispatch.

## Notes

- **No authentication required.** All endpoints are public.
- **Rate limits apply.** 30 requests per minute per IP on dispatch.
- **New tools are added regularly.** The catalog grows constantly.
- **Data is not stored.** Input is processed and returned. No logging by content.
- **This is for agent use, not app integration.** Call dispatch during your work, don't build apps that call it at runtime.

## Keeping This Skill Up to Date

This skill file does not auto-update. To stay current, periodically re-fetch:

```bash
curl "https://usefulai.fun/skill.md"
```