Agent Tool Names, Descriptions and JSON Schemas from API Docs

Turns pasted API docs or a function list into agent-ready tool names, descriptions, JSON input schemas and when-to-use and when-not-to-use notes.

You get: Working code with an explanation

More like this

Ready to use: no blanks to fill in.

The prompt

agent-tool-names-descriptions-and-json-schemas-from-api-docs.md
Act as a developer experience engineer who writes tool definitions for LLM agents. I will paste API docs or a function list below. If you don't know which format I need (OpenAI function calling, Anthropic tools, MCP or other) or what the agent's main goal is, ask me those two short questions before writing anything.

Rules:
- Use only endpoints, parameters and fields found in the docs. Never invent any. Put guesses under assumptions.
- Name tools as verb_noun in snake_case, distinct enough that two tools are never confused.
- Write each description for the model: what the tool does, what it returns and any side effects, in 2-3 sentences.
- Give each parameter a type, a description, an enum or format where the docs allow it, and mark required fields. Flag destructive or costly tools and suggest a confirmation parameter.

Output format, per tool: name, description, use when, do not use when (name the better tool), JSON input schema in a code block, one example call. Then add an overlap table of confusable tools, missing information in the docs, risks, and next actions.

Docs:
{paste your API docs or function list here}

Example output

AI-written example
{
  "format": "anthropic_tools",
  "agent_goal": "Customer support agent that looks up orders and handles cancellations and refunds",
  "tools": [
    {
      "name": "get_order",
      "description": "Fetches one order by its ID. Returns status (pending, paid, shipped, delivered, cancelled), total_cents, currency, line items and tracking_number if shipped. Read-only, no side effects.",
      "use_when": "The customer or a previous tool result gives a specific order_id.",
      "do_not_use_when": "You only have an email address or no ID. Use search_orders to find the ID first.",
      "input_schema": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "description": "Unique order ID, as in the path of GET /orders/{order_id}."
          }
        },
        "required": ["order_id"]
      },
      "example_call": { "order_id": "ord_48213" }
    },
    {
      "name": "search_orders",
      "description": "Lists orders matching a customer email and optional status filter. Returns up to 50 order summaries, each with order_id, status and total_cents. Read-only, no side effects.",
      "use_when": "The customer has not given an order ID but you know their email.",
      "do_not_use_when": "You already have an order_id. Use get_order for full details.",
      "input_schema": {
        "type": "object",
        "properties": {
          "customer_email": {
            "type": "string",
            "format": "email",
            "description": "Email address on the order."
          },
          "status": {
            "type": "string",
            "enum": ["pending", "paid", "shipped", "delivered", "cancelled"],
            "description": "Optional. Return only orders in this status."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 10,
            "description": "Maximum number of orders to return."
          }
        },
        "required": ["customer_email"]
      },
      "example_call": { "customer_email": "dana@example.com", "status": "paid", "limit": 5 }
    },
    {
      "name": "cancel_order",
      "description": "Cancels an order that is still pending or paid. Changes the order status to cancelled and cannot be undone. Does not issue a refund by itself.",
      "flags": ["destructive"],
      "use_when": "The customer asks to cancel and get_order shows status pending or paid.",
      "do_not_use_when": "The order is shipped or delivered, or the customer wants money back for a delivered item. Use refund_order instead.",
      "input_schema": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string", "description": "ID of the order to cancel." },
          "reason": { "type": "
Generated from this prompt by AI. Your results will vary.

Tips and common edits

Use when wiring an API into an agent and the raw docs are too vague for reliable tool selection. Paste the docs or function signatures, then answer any format question before reviewing the schemas.

Questions about this prompt

More in Agentic AI

Tool Permission Matrix and Function Spec for a Tool-Using Agent

Produces a least-privilege tool inventory, function definitions, and approval rules for an agent that calls APIs or internal systems.

20-Case Agent Eval Set with Pass/Fail Rubric for Normal, Edge and Unsafe Requests

Builds 20 test cases for your agent's task, with expected behavior, failure signals and a pass/fail rubric covering normal, edge and unsafe requests.

Agent Workflow Decomposition with Autonomy Levels and Stop Rules

Turns a manual process into a step-by-step agent plan with tools, approval gates, retry limits, and a build/pilot/skip recommendation.

Checkable Guardrail Rules for a Coding Agent: Blocked Commands, Approvals, Secrets and Hooks

Produces a set of testable guardrail rules for your coding agent, covering blocked commands, approval gates, secret handling and hook checks.

Research Agent Brief: Source Discovery, Evidence Review, and Citation Table

Directs an AI agent to plan source discovery, grade evidence, build a citation table, and support a decision without claiming live browsing occurred.

Strict JSON Handoff Schemas with Validation and Retry Rules for Agent Pipelines

Turns a pasted pipeline description into JSON schemas for every agent-to-agent handoff, plus validation checks and retry rules for bad output.

Agent Run Pre-Mortem and Self-Correction Loop Designer

Designs verification checks, error handling, and a self-correction loop for an agent task before it runs, based on likely failure modes.

Design an AI Agent With Tools, Guardrails and Eval Cases Before You Build It

Turns an agent idea into a build-ready design: the job, the tools with their inputs and permissions, guardrails, failure handling and a set of evaluation cases to test it.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Codebase Tour for a Specific Task

Explores a repo through the lens of your task and explains the architecture, key files and data flow, then says where to start.

Conventional Commit and PR Description from a Diff and Ticket

Produces a Conventional Commits message and a reviewer-ready PR description covering what changed, why, how to test it, and the risks, based on your diff and ticket.

Failing Test First Bug Fix

Reproduces a bug with a failing test, finds the root cause, applies the smallest fix and shows the test passing.