agentsop-http-tool-wrapping

What it does

Guides turning an external HTTP API into an LM-friendly tool surface. Emphasizes one tool per user intent rather than one endpoint per tool, and provides criteria for when to activate, how to name and shape tools, how to flatten and type inputs, how to handle errors, pagination, authentication, idempotency, and framework bindings across multiple tool ecosystems.

How it works

Outlines activation triggers: when a coder agent must expose an external HTTP API to a model, or when selecting which endpoints to surface, or when existing tools return too much JSON or fail due to rate limits. Establishes core mental model: tool surface is a simplified, model-facing subset of the API; the surface includes a name, description, and a typed input schema. Provides a step-by-step workflow (OP-1 to OP-10) for triage, naming by intent, creating a typed input schema, injecting auth at the wrapper boundary, ensuring idempotency for mutations, and binding the framework across LangChain, CrewAI, MCP, OpenAI, and Anthropic.

Key steps include:

• Step 1: Triage endpoints to surfaced tools with intent labels, cap around 10.
• Step 2: Name by intent using verb_object format.
• Step 3: Flatten API params into a typed schema with description for each field.
• Step 4: Translate errors into a structured LM-readable JSON error object.
• Step 5: Shape output with a compact schema, including pagination surface when applicable.
• Step 6: Inject authentication at the wrapper boundary; no secrets in tool args.
• Step 7: Implement idempotency for mutating calls with per-operation keys.
• Step 4–10: Framework bindings and detailed SOP for error handling, pagination, and response shaping.

When to use it

Use when exposing a third-party or internal HTTP API to an LLM, deciding which endpoints should be tools, or when existing tools return too-large JSON or face rate limits, timeouts, or pagination issues. It also applies when porting the same tool across multiple tool ecosystems (OpenAI function calling, Anthropic tool_use, MCP, LangChain @tool, CrewAI BaseTool).

What it can touch

The skill prescribes how to design the tool surface and input/output schemas, error handling, and framework bindings. It does not enumerate specific implementation touches beyond the described SOP; exact touch points are determined by the defined steps (typed input schema, output model, error structure, idempotency header, and per-framework bindings).

Caveats

Cites multiple external sources for guidance and requires adherence to a typed input schema (no free-form kwargs), controlled error codes, and explicit authentication handling inside the wrapper. It cautions against mega-tools unless the API is genuinely uniform and emphasizes surface triage to avoid oversized tool catalogs. License: MIT.