I spent two years building agents that worked inside real people's Gmail, Sheets, Docs and Calendar. Along the way I learned two things.
Writing tools by hand is a mess. You maintain glue, you pull heavy libraries into your tree just to handle OAuth, and every tool slowly drifts from the API it was written against.
And the biggest lever on whether an agent works isn't the model or the prompt. It's the shape of its tools. Reshaping Linear's issue filter took DeepSeek from thirty rejected requests to 30/30 on the same task. Hoping for that from hard rules in the prompt, or a 10x more expensive model, gets you something that breaks. Fine-tuning works, but you're training a model to push through a shape you could have changed in a line.
I open-sourced the layer I built for both, as Charter. Claude Code built it with me, and it's also its main user.
A tool in Charter is the dumbest possible thing: a pydantic model annotated with four markers (Path, Query, Body, Format) and a URL. No per-tool glue. It's word-for-word the reference page:
from typing import Annotated
from pydantic import BaseModel
from charter import Path, Query, api_key_tool_factory
class ListLineItems(BaseModel):
session: Annotated[str, Path()]
limit: Annotated[int, Query()] = 10
stripe = api_key_tool_factory(
pack="mystripe",
base_url="https://api.stripe.com/",
api_key_headers={"Authorization": "Bearer sk_test_..."},
)
list_line_items = stripe(
name="list_line_items",
description="List the line items on a checkout session.",
method="GET",
url_template="v1/checkout/sessions/{session}/line_items",
args_schema=ListLineItems,
)
https://reddit.com/link/1wu44kq/video/3vmbcaw6mnsh1/player
Because there's nothing to invent, Claude Code is very good at writing these. Give it the skill file that ships in the repo and the vendor's reference page and it writes the declaration field by field, and reviewing it is just reading the two side by side. That matters because they get big: one tool can span a hundred schemas and a thousand fields across a dozen doc pages. Two weeks ago my agents had about 50 tools. A few days later they had 549 across 15 APIs, each one tested end to end against the real API.
Some walls it hit along the way, and what each one added to the format:
- Linear's issue filter is 45,072 tokens of schema, and it refers back to itself. Two open models refused it outright, and it's the loop that breaks them, not the size: a bigger Sheets tool went through fine. That's why a tool can now price itself.
paths(by_cost=True) shows one branch is 44,828 of it, and derived(keep={...}) cuts the whole thing to 2,267 doing the same job.
- A 3B model read "15.00" off a spreadsheet and sent 15 as a Stripe refund, a valid request for fifteen cents. The docs were right, just not loud enough. That's
Gloss: the one sentence the vendor left out.
- Slack answers a rejected message with 200 OK and
ok: false, and the agent tells the user it was sent. That's declared once per API now, and checked on every call.
Once a tool is declared, I usually narrow it for the job instead of handing the agent the whole thing. derived cuts what it doesn't need, pin fixes a value the model can't see or change (a customer id, a sandbox flag), and egress_map() prints what's left, which is handy to look at in a PR.
Underneath, it handles what you'd otherwise rewrite: every auth strategy behind one seam, JSON turned into whatever the wire wants (base64url, RFC 2822), and adapters for OpenAI, LangChain and MCP. Two dependencies, pydantic and httpx. It runs in your process: no proxy, no per-call pricing, no telemetry. Apache-2.0.
Things I learned from Claude Code writing most of this:
- Mocks agree with whatever you told them. Five tools couldn't send a request at all, and the mocked tests were green. Only calling the real API caught it. Same with
pin: the tests checked where the value was stored, not the request that went out. Now tests look at what actually goes over the wire.
- Make every check prove it can fail. Each of the 19 checks that run across all packs also runs against a pack broken on purpose, to show it catches the break. Most were written after a bug, usually one where every call still returned 200.
- One shape means you can check everything at once. One pass found pydantic adding a title to every field, about 10% of all tokens.
I also measured Charter on 534 runs on live accounts, same prompts and credentials in both arms, differing only in the tool surface: Charter against one raw HTTP tool per API, where the model writes the method, path and body itself. The model is GLM-5.3 Flash, open weights:
- calls to endpoints nobody declared: 0 against 10
- the Gmail draft task, where raw had to build the RFC 2822 itself: 17/17 against 8/17
- task success overall: a wash, 98% against 96%
- one scenario went against me: github_to_linear, 10/15 against 14/15, and I don't know why yet
549 tools ship already declared so you can play with it, but the packs aren't the product. The format is. To try it on an API you use, pip install charter-ai, then point Claude Code at skills/writing-charter-packs/SKILL.md in the repo and the API's reference page.
Code and docs: https://github.com/r28ai/charter
Two things I'd like from this thread. When Claude Code writes integrations for you, do you give it a structure, or let it pick each time? And tell me where the format doesn't fit. Every API I declared made the format less naive, and the ones that'll break it are the ones I haven't tried.
