/agentsop-http-tool-wrapping

name: agentsop-http-tool-wrapping
version: 0.1.0
description: |
  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.
domain: coder-agent / tool-construction
audience: engineers wiring external APIs into LLM agents
trigger_keywords:
  - "wrap an API as a tool"
  - "expose REST endpoint to agent"
  - "function calling for my API"
  - "MCP server for existing API"
  - "tool returns too much JSON"
  - "agent rate limited / 429"
  - "GraphQL / RPC as agent tool"
when_to_use:
  - "exposing a third-party or internal HTTP API to an LLM agent"
  - "deciding which of N endpoints deserve to become tools"
  - "an existing tool dumps raw JSON and the model hallucinates fields"
  - "tool calls fail on rate limits, timeouts, or pagination"
  - "porting the same tool across OpenAI / Anthropic / MCP / LangChain / CrewAI"
when_not_to_use:
  - "the API is already an MCP server you only consume (just connect)"
  - "no external I/O — pure local computation (write a plain function tool)"
  - "designing the upstream API itself (that's API design, not tool wrapping)"

HTTP / External API → Agent Tool · SOP

> Source posture: every non-trivial claim is cited inline with short tags like > `[oai/fc]`, `[anthropic/tooluse]`, `[lc/tools]`, `[mcp/spec]`, `[apxml/schema]`. > Resolve them against `references/R1-source-evidence.md` for full URLs. Reusable > code shapes live in `references/R2-pattern-library.md`.

---

1. 何时激活 (When to Activate)

Activate when a coder agent must make an **external HTTP API callable by an LLM**. Concrete triggers:

• The task says "give the agent access to <some API>", "add a tool that calls

<service>", "wrap our REST/GraphQL/RPC endpoint as a function the model can use".

• You are choosing which of N endpoints become tools, or how to name them.
• An existing tool returns a huge JSON blob and the model hallucinates field

names, or burns context re-reading it.

• Tool calls die on `429`, timeouts, or unpaginated list endpoints.
• You need the *same* tool to run under OpenAI function calling, Anthropic

`tool_use`, an MCP server, LangChain `@tool`, and CrewAI `BaseTool`.

**Do not activate** when: the API is already exposed as an MCP server you merely consume (just connect it); the "tool" is pure local computation with no network I/O (write a plain typed function); or you are designing the upstream API itself.

This is a **tool-construction** skill — sibling to the framework SOPs (`langgraph-sop`, `crewai-sop`) which decide *whether/where* tools run. Once you know you need a tool, this skill decides *what shape it takes*.

---

2. 核心心智模型 (Core Mental Model)

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

A REST API is designed for *programmers* who read docs, hold a mental model of resources, and compose calls. An agent tool is designed for a *language model* that sees only a name, a description, and a JSON schema — and must decide, mid-reasoning, whether this is the thing to call. These are different audiences, so the surface must be *re-cut*, not *mirrored*.

> "Tool descriptions are often more important than code comments because the LLM > directly uses them for reasoning." `[apxml/schema]`

Four load-bearing consequences:

1. **Intent, not CRUD.** The unit of a tool is a *thing the agent wants to accomplish* (`cancel_order`, `find_customer_by_email`), not an HTTP verb on a resource (`DELETE /orders/{id}`). One intent may compose several endpoints; one endpoint may serve zero intents (admin/batch/webhook-out endpoints get dropped). Surface intent, not the verb table `[zuplo/agent-ready]`.

2. **The schema is the prompt.** The model never sees your code. It sees the tool name, the description, and each field's `description=`. Every field needs units, format, enum values, and an example *aimed at the model* — "if a field is a date, specify ISO 8601 vs Unix timestamp" `[apxml/schema]`. A typed schema (Pydantic / JSON Schema) is non-negotiable because it is *both* the validation layer and the documentation the model reads `[lc/tools]`.

3. **The response is context, and context is scarce.** A 10 MB JSON payload is not "data the agent has" — it is tokens the agent must pay for, re-read, and can misquote. Shape the response down to the fields the agent needs to *reason or act* on. Returning raw upstream JSON is the second most common anti-pattern after 1:1 mapping.

4. **The model cannot promise call discipline.** It may emit zero, one, or several calls — "best practice [is] to assume there are several" `[oai/fc]` — retry on its own, or be resumed by the framework. So the *wrapper* owns reliability (timeout, retry, rate-limit) and *safety* (idempotency on mutations). You cannot prompt these guarantees into existence; you build them into the tool. (Side-effect safety is deep enough to be its own skill — cross-link **`llm-tool-idempotency`** for any mutating tool.)

The pre-LLM analog: you are writing an **SDK for a non-deterministic, amnesiac junior dev who reads only the function signature** — generous docstrings, narrow typed inputs, small clean returns, and total robustness to being called wrong.

---

3. SOP 工作流 (Standard Operating Procedure)

Walk top-down. Each step has a gate — if it fails, fix it before adding surface.

Step 1 · Triage: which endpoints deserve to be tools?

List every endpoint × verb. For each, ask