---
title: "Agents"
description: "The same tools over MCP and Pi and OMP and the AI SDK. What they take and what they refuse and what the model reads back"
canonical_url: "https://encodings.agntn.dev/guide/agents"
---
# Agents

> The same tools over MCP and Pi and OMP and the AI SDK. What they take and what they refuse and what the model reads back

## Same tools, every host

Four hosts, one set of executors. The MCP server, the Pi and OMP extensions and `@agntn/encodings/ai` all call `src/tool-operations.ts`. Same arguments, same checks, same text back. A fix lands once. This site runs those executors too. Every `Full tool response` dialog here is exactly what a model reads.

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Does
    </th>
    
    <th>
      Arguments
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        encodings_encode
      </code>
    </td>
    
    <td>
      Write text or bytes in an encoding
    </td>
    
    <td>
      <code>
        encoding
      </code>
      
      , <code>
        input
      </code>
      
      , <code>
        inputFormat
      </code>
      
      , <code>
        options
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        encodings_decode
      </code>
    </td>
    
    <td>
      Read text back into bytes
    </td>
    
    <td>
      <code>
        encoding
      </code>
      
      , <code>
        text
      </code>
      
      , <code>
        outputFormat
      </code>
      
      , <code>
        options
      </code>
      
       (<code>
        alphabet
      </code>
      
      , <code>
        check
      </code>
      
      , <code>
        m
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        encodings_identify
      </code>
    </td>
    
    <td>
      <a href="https://encodings.agntn.dev/guide/identify">
        Rank
      </a>
      
       the encodings a string decodes in, or peel them off
    </td>
    
    <td>
      <code>
        text
      </code>
      
      , <code>
        limit
      </code>
      
      , <code>
        peel
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        encodings_info
      </code>
    </td>
    
    <td>
      The list, one family, or one encoding with its alphabet
    </td>
    
    <td>
      <code>
        encoding
      </code>
      
       or <code>
        family
      </code>
      
      , both optional
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        encodings_charset_convert
      </code>
    </td>
    
    <td>
      Read text as bytes in one <a href="https://encodings.agntn.dev/guide/code-pages">
        code page
      </a>
      
       and write them in another
    </td>
    
    <td>
      <code>
        text
      </code>
      
      , <code>
        from
      </code>
      
      , <code>
        to
      </code>
    </td>
  </tr>
</tbody>
</table>

## What a model reads

A header line, then the value.

```text
bech32 → 20 bytes as hex (prefix "bc", witnessVersion 0):
751e76e8199196d454941c45d1b3a323f1433bd6
```

`outputFormat` is `auto` by default. Clean UTF-8 comes back as a quoted string, anything else as hex. Clean means no control characters, no bidi overrides, no line separators. Why so strict? A decoded string could rewrite the line it sits on, and a model would believe it. Ask for `utf8` explicitly and you get it, escaped.

`encodings_identify` gives each candidate two lines. The rank, the encoding, the score and the reasons. Then the byte count and the bytes.

```text
1. base32 0.593; padding fits the block length, decodes to readable text
   11 bytes, text "Hello World"
```

With `peel: true` the same lines list layers, outermost first, under a count. A guess nothing backs says so.

```text
1 layer, outermost first:
1. base64 (unconfirmed guess) 0.021
   12 bytes, hex 53616c7465645f5fb196bea1
```

Everything the next call needs is in the text. An MCP client sees nothing else. Pi, OMP and the AI SDK also get structured `details`.

## What they refuse

Every schema is closed. A misspelled argument is an error, not a quiet default.

```text
Invalid arguments: unknown property "encodng"; takes encoding, input, inputFormat, options
```

A checksum that doesn't match is a tool error with the reason. The session carries on.

```text
encodings_decode failed: base58: checksum does not match
```

The bounds sit in the schema. The executor checks them again, since a host may skip schema validation. Text up to 100000 characters. Base58 up to 10000, because base58 is quadratic. Real ones are addresses and keys, nowhere near that long. At most 20 `identify` candidates or layers. Nothing is written anywhere, and there's no network to reach.

## MCP

```bash
encodings mcp
claude mcp add encodings --scope user -- npx -y @agntn/encodings mcp
```

Or in a client's config:

```json
{
  "mcpServers": {
    "encodings": { "command": "npx", "args": ["-y", "@agntn/encodings", "mcp"] }
  }
}
```

stdio, every tool read-only and idempotent.

## Remote MCP

No Node on your side? Or a client that only takes a URL? This site serves the same five tools over Streamable HTTP, at `https://encodings.agntn.dev/mcp`.

```bash
claude mcp add --transport http encodings https://encodings.agntn.dev/mcp
```

```json
{
  "mcpServers": {
    "encodings": { "type": "http", "url": "https://encodings.agntn.dev/mcp" }
  }
}
```

It's the Docus MCP server with the encoding tools bolted on. Same tools as `encodings mcp`, same answers byte for byte, refusals included. Misspell an argument and it tells you so:

```text
Invalid arguments: unknown property "encodng"; takes encoding, input, inputFormat, options
```

Same typo, same complaint, either way. Docus adds two tools of its own. `list-pages` lists this site and `get-page` hands one page back as Markdown. So a model can read up on [Base58Check](https://encodings.agntn.dev/encodings/base58#base58check) before it trusts a checksum.

The catch: every argument travels to a Cloudflare worker. The site keeps none of it, but you can't check that from your side. Decoding an address there is fine. A private key on its way into WIF isn't, so that one gets `npx -y @agntn/encodings mcp`.

## Pi and OMP

```bash
pi install npm:@agntn/encodings
omp install @agntn/encodings
```

Both extensions are declared in `package.json` and ship as source the host loads directly.

## AI SDK

```ts
import { generateText } from "ai";
import { encodingAiTools } from "@agntn/encodings/ai";

await generateText({
  model,
  tools: encodingAiTools,
  prompt: "What does 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa decode to?",
});
```

`encodingAiTools` holds every one of them under the same names. Each one is exported alone too, `encodingsDecodeTool` and friends, if you'd rather hand a model fewer.


## Sitemap

See the full [sitemap](https://encodings.agntn.dev/sitemap.md) for all pages.
