Takes a function description (name, purpose, parameters) and writes a valid Anthropic tool_use JSON schema, with type annotations, required fields, and a description for each parameter. Adds a Python client.messages.create(tools=[...]) snippet only when asked. Use when wiring a Claude agent to a function or API, designing tools for a multi-agent system, or documenting an existing tool for agent consumption.
Pack api-builderTier standardJob Build on the Claude APIv1.0.2
In Claude Code, with the api-builder plugin installed, invoke it as:
/api-builder:tool-use-schema-writer
Try it
A realistic prompt from the skill's acceptance evals:
Write the Claude tool definition for this Python function in our Acme order service:
def search_orders(customer_id: str, status: str | None = None, placed_after: str | None = None, sort: str = 'desc', limit: int = 20):
"""Find a customer's orders. status is one of pending, shipped, delivered, cancelled. placed_after is an ISO date. sort is by order date, asc or desc. limit 1-100."""
The agent also has a separate get_order(order_id) tool, so the descriptions need to keep them apart.
What a good result looks like
Descriptions are decision conditions, not function names restated."Gets the weather" is not a description — "Returns the current temperature and conditions for a given city. Call this when the user asks about current weather, not forecasts." is.
Required arrays are never omitted. An omitted required array means all fields are optional — the model will skip fields the function actually needs and the call will fail at runtime.
Enum values always have descriptions."enum": ["asc", "desc"] without a description leaves the model guessing which to use.
How it's checked
Measured against plain Claude Code (2026-10-23): it met 87% of its checks, against 79% without it, and a blind judge preferred the agent without it. How skills are checked
38 assertions across 5 acceptance evals, and 7 trigger queries. Every skill's checks
What the output must do
Produces a valid Anthropic tool definition with name, description, and input_schema of type object
The top-level description names a decision condition (when to call search_orders versus get_order), not just a restatement of the function name
A required array is present and contains customer_id; every name in required exists in properties
Every parameter has a non-empty description, and limit states its valid range (1-100)
The status and sort enums list their values with a one-phrase explanation of each value
Gives the definition without a Python usage snippet, since none was asked for
Does not invent parameters, enum values, or behaviors not in the supplied signature and docstring
It produces a tool definition with a name, a description and an input_schema of type object, and ctx / RequestContext is not one of the properties
The top-level required array contains the clinic code, visit type, start time and contact, and does not contain duration, vet id or notes
The pet id is not unconditionally required: the definition or reply states it is needed for every visit type except new_patient and must be left out for new_patient
contact is a nested object with its own required array containing phone, with email and SMS reminders optional
It flags that the comment says bookings can be made up to 90 days ahead while the code enforces 60, and does not state 90 days as the limit
Duration is limited to 15, 30 or 45 with a default of 30, and the definition states that dental visits need 45 minutes
It says cancelling is not supported by this function and does not add a cancel parameter, action or mode to the tool
It does not list six clinic codes as an enum or as fact, since the source gives only the example PVG-03
It delivers two tool definitions, each with a name, a description and an input_schema, and does not stop at questions
The quote tool's required array includes origin zip, destination zip and weight, and dimensions is not in it
The weight parameter's description states the unit is pounds
Service level offers ground, 2-day and overnight, and the reply says that list is unconfirmed and should be checked
Each tool's description says when the agent should call it, so a tracking question and a pricing question map to different tools
It does not state a tracking number format or pattern, a weight limit, carrier names or a dimension unit as fact
It does not describe the lookup's return fields as fact, and says what the lookup returns is not yet known
It produces a tool definition with a name, a description and an input_schema of type object whose properties include the order reference, the amount and the reason
The amount parameter is an integer in minor units (pence) and its description says so; it is not defined as pounds or as a decimal
It flags that the spec caps amount_minor at 25000, which is £250 and below the £500 policy, and does not set the maximum to 50000
It flags that the spec lists amount_minor as required while its description says to omit it for a full refund
goodwill is either left out of the reason values or marked as deprecated with customer_request to be used instead
The definition states that reason_note is needed when the reason is other and is limited to 280 characters
It does not add parameters the spec does not have, such as a currency, a customer id or a refund method
The reply contains no Python client code
It delivers a tool definition with a name, a description and an input_schema, and does not stop at questions
The required array contains the SKU and the price, and does not contain store or until
The price parameter's description states the unit is dollars
It says that leaving store out meaning all stores is unconfirmed and should be checked
It does not state what --force does; force is either left out of the tool or included with its effect marked as unknown
The until parameter is described as a date in the YYYY-MM-DD form shown in the example
It does not state a SKU pattern, a price minimum or maximum, or a range of valid store numbers as fact; any such constraint is marked as an assumption
The reply is the JSON definition with at most a few lines of notes, and contains no Python client code
When it should and shouldn't activate
Should activate:
Write the tool_use JSON schema for this function so Claude can call it
Turn this TypeScript API client method into an Anthropic tool definition
I have three functions for my agent — write their tool schemas so the model picks the right one
Document this existing endpoint as a tool the agent can consume, with required fields
Should leave to another skill:
Design the control loop for my tool-using agent — stop conditions and retries
Split this workflow across an orchestrator and specialist subagents
Draft the OpenAPI contract for our new public REST API