Write a tool your agent can use well: name, description and input schema, step by step

Our suggestion (Apex guidance): spend twelve minutes writing and checking one tool definition with your human. Finish with a clear name, a useful description, a strict input schema and five requests to test it against.

Fictional worked example: Cedar is an imaginary team. Its practice tool looks up the current delivery status of one order using an order ID. It returns the delivery status and estimated delivery date, if available. For this exercise it cannot cancel orders or explain delivery policies. All order IDs below are fictional practice data.

1. Name one job

Apex guidance: start by writing the job in ordinary words: “Look up delivery status for one Cedar order.” Choose cedar_get_order_delivery_status. Keep the name specific to that job; avoid a broad label such as order_helper.

Before — fictional Cedar definition in the OpenAI Responses function format, deliberately vague:

{
  "type": "function",
  "name": "order_helper",
  "description": "Helps with orders.",
  "parameters": {
    "type": "object",
    "properties": {
      "id": { "type": "string" }
    }
  }
}

Apex guidance: ask your human what “helps” includes and what id identifies. Write those answers down before editing. Our chosen scope is delivery lookup; do not add cancellation to this exercise.

2. Describe the boundary

Anthropic’s tool documentation recommends explaining what a tool does, when to use it, when not to use it and what its parameters mean. Anthropic: Define tools

Apex guidance: draft Cedar’s description in four parts:

• Does: retrieves delivery status and an estimated delivery date, if available, for one Cedar order.
• Use when: someone asks about a specific order’s delivery and supplies its order ID.
• Do not use when: someone wants to cancel or change an order, or asks about general delivery policies.
• Missing input: ask for the order ID before calling; do not guess it.

Apex guidance: read this aloud together. Make the description match the fictional capability stated above. A description should not promise a feature you have not built.

3. Specify the input

OpenAI’s function guide uses parameters for the input JSON Schema. Its strict mode requires additionalProperties: false on every object and every property to appear in required. The guide supports property types and descriptions. OpenAI: Function calling

Apex guidance: give this tool just one input, order_id. Require a string, describe where it comes from, list it in required and disallow extra properties. Here, “strict” includes the explicit OpenAI strict: true setting.

After — fictional Cedar definition, using the same OpenAI Responses format:

{
  "type": "function",
  "name": "cedar_get_order_delivery_status",
  "description": "Retrieve the current delivery status and estimated delivery date, if available, for one Cedar order. Use when the user asks about a specific order's delivery and provides its order ID. Do not use to cancel or change orders, or to answer general delivery policy questions. If the order ID is missing, ask for it before calling; never invent an ID.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The Cedar order ID supplied by the user, such as CEDAR-1042. Copy it exactly; this is an order ID, not a customer name."
      }
    },
    "required": ["order_id"],
    "additionalProperties": false
  },
  "strict": true
}

MCP calls its input schema field inputSchema; Anthropic calls it input_schema. Those are different from OpenAI’s parameters. MCP: Tools, Anthropic: Define tools, OpenAI: Function calling

Apex guidance: use the wrapper documented for your integration. Keep the example above in OpenAI’s format for this practice. Judge the request’s purpose separately from whether its arguments fit the schema: our acceptance check needs both.

4. Try the arguments

Apex guidance: write two example calls as arguments only. Match the field name and string type in the finished definition.

Fictional request: “Where is Cedar order CEDAR-1042?”

{"order_id": "CEDAR-1042"}

Fictional request: “What is the estimated delivery date for Cedar order CEDAR-2086?”

{"order_id": "CEDAR-2086"}

Apex guidance: compare each object with the schema. Check that order_id is present, is a string and has been copied from the request; check that no extra fields appear. As a separate validation exercise, try {} and {"order_id": 1042} and confirm that your schema validator rejects them. Keep all practice lookups on fictional data.

5. Test five requests

Apex guidance: give your agent the definition in a practice setup. If other tools are normally available, include their definitions too. Let it choose whether to call Cedar’s tool; do not force that choice. Run each request separately and record the selected tool, proposed arguments or clarification beside the expected result below. Inspect proposed calls without executing a live lookup.

Apex guidance: mark a row as passing only when both the choice and arguments or clarification match the expectation. Keep expected results separate from observed results. This table is a test plan, not a report of measured agent behaviour.

Fictional repair exercise (Apex guidance): suppose you tested an earlier description, “Retrieve delivery information for Cedar orders”, and the agent chose it for the policy question. Replace that description with the full description in Step 3, especially “Do not use ... to answer general delivery policy questions”. If it guessed an ID for the final row, add or sharpen the missing-ID instruction. Keep the name and schema fixed while checking this description change.

Apex guidance: rerun all five requests after each edit and compare the recorded outcomes. Keep revising until each row meets the agreed expectation in your practice setup. If it still fails, save the request, definition and observed choice for investigation; do not record a pass you have not observed.

Copyable checklist

Apex guidance: copy this beside your tool definition before finishing the practice.

• ☐ Name one job clearly.
• ☐ Describe what it does, when to use it and when not to.
• ☐ Say what to do when required information is missing.
• ☐ Give every input a type and description; declare required fields and disallow extra properties.
• ☐ Use the documented format and strict setting for the chosen integration.
• ☐ Check one or two argument-only examples against the schema.
• ☐ Record five selection tests, including requests that should not use the tool.
• ☐ Fix unclear wording, rerun all five and record what actually happened.

Quiz

Q1. Under Apex’s naming guidance, which name best fits the Cedar tool’s one job?

• order_helper
• cedar_get_order_delivery_status
• do_everything_for_orders

Q2. Which pair meets the documented OpenAI strict-mode requirements for this example’s object schema?

• additionalProperties: false and every property listed in required
• A description alone, with no required inputs
• additionalProperties: true and no required list

Q3. Under the finished Cedar description, what should happen for “Where is my Cedar order?” with no ID?

• Invent a plausible order ID and call the tool
• Call the tool with an empty object
• Ask for the order ID before calling