Skip to content

agentsope/SkillAlchemy / skills/agentsop-http-tool-wrapping

agentsop-http-tool-wrapping

Verified

Decision protocol for wrapping a REST / GraphQL / RPC API as a tool an LLM agent can call. The load-bearing premise: the *tool surface* is an LM-friendly subset of the *API surface* — one tool per user intent, not one per endpoint. Activates when a coder agent must expose an external HTTP API to a model (function calling, tool_use, MCP, LangChain `@tool`, CrewAI `BaseTool`). Encodes the *what to surface, how to name, how to shape, how to fail* — not any single framework's API. ~80% of agent tools in production are HTTP wrappers; this is the SOP for getting them right.

FileKindSize
README.mdmarkdown2.7 KB
SKILL.mdskill md23.2 KB
intermediate/operation_candidates.jsonconfig7.7 KB
references/R1-source-evidence.mdmarkdown8.7 KB
references/R2-pattern-library.mdmarkdown8.2 KB
# http-tool-wrapping

SOP skill for **wrapping a REST / GraphQL / RPC API as a tool an LLM agent can
call**. Phase D coder-agent skill (high-frequency: ~80% of agent tools in
production are HTTP wrappers, and no unified skill existed for the pattern).

## Core thesis

> **The tool surface is an LM-friendly subset of the API surface — one tool per
> intent, not one per endpoint.**

A REST API is built for programmers who read docs and compose calls. An agent
tool is built for a language model that sees only a name, a description, and a
JSON schema. The surface must be *re-cut* for that audience, not mirrored.

## What's here

| File | Purpose |
|---|---|
| `SKILL.md` | The skill. 7 sections: activation, mental model, SOP, operation models (OP-1…10), dilemma cases (DC-1…3), anti-patterns, cross-framework table. |
| `references/R1-source-evidence.md` | Every inline citation with quoted evidence, grouped by topic. |
| `references/R2-pattern-library.md` | Copy-pasteable code shapes: typed schema, retry+timeout client, pagination, error contract, auth injection, framework-binding snippets. |
| `intermediate/operation_candidates.json` | Structured capture of the 10 operations, anti-patterns, dilemma cases, and key quotes used to build `SKILL.md`. |

## How to use

1. **Triage** the API to ≤10 intent-bearing operations (SKILL §3 Step 1 / OP-1).
2. **Name** each tool by intent, define a **typed flattened schema** with
   model-facing field descriptions (Steps 2–3).
3. Build the wrapper's robustness layer: **error translation, response shaping,
   pagination, auth injection, retry/timeout** (Steps 4–6, OP-5…8).
4. For mutating tools, add an **idempotency key** and defer the full protocol to
   the sibling **`llm-tool-idempotency`** skill (Step 7 / OP-9).
5. **Bind** the one Pydantic schema into your framework — OpenAI / Anthropic /
   MCP / LangChain / CrewAI all consume `model_json_schema()` (OP-10, §7).

## Relationship to sibling skills

- `langgraph-sop`, `crewai-sop` — decide *whether/where* tools run and how the
  graph/crew orchestrates them. This skill decides *what shape each tool takes*.
- `llm-tool-idempotency` — owns side-effect safety (exactly-once, dedup).
  This skill only flags the hook on mutating tools (OP-9).
- Bounded-loop skill — owns agent loop bounding; referenced for paginated /
  polling tools (OP-6, DC-3).

## Source material

Built from `langgraph-sop` (tool definition + binding) and `crewai-sop`
(per-agent tool scoping), plus official docs: OpenAI function calling, Anthropic
`tool_use`, MCP / FastMCP, LangChain tools, CrewAI tools — and external evidence
on rate limits, retries, pagination, idempotency, and tool-schema design (see
`R1`).

`name: http-tool-wrapping` · `version: 0.1.0`
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall