Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
AI & knowledge

agentsop-http-tool-wrapping

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.

agentsope · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add agentsope/SkillAlchemy --skill agentsop-http-tool-wrapping

About this skill


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 ", "add a tool that calls ", "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

Read the complete source ↗