Designing Reliable Tool Schemas

A tool schema is the contract between a language model and your application. It tells the model what the tool does, when to use it, and what arguments are required. It tells your application what shape of input to expect and validate.

Poor tool schemas create unreliable agents. The model may call the wrong tool, omit required arguments, invent fields, pass vague values, or misunderstand the tool’s purpose. Strong schemas make the correct behavior easier and the incorrect behavior harder.

A reliable schema has five qualities:

1. Clear tool name
2. Specific description
3. Typed parameters
4. Meaningful field descriptions
5. Constraints such as enums, required fields, and formats

Start with a precise tool name

Tool names should be action-oriented and unambiguous.

Weak names:

handle_data
process
lookup
run

Better names:

get_customer_profile
search_policy_documents
create_refund_request
summarize_pdf_document
run_unit_tests

A good name helps the model understand the tool’s purpose even before reading the description. Avoid names that imply more capability than the tool actually has. If a tool only creates a refund request for human approval, do not name it issue_refund.

Write descriptions that define when to use the tool

A weak description says what the tool is in vague terms:

Searches stuff.

A strong description says what the tool searches and when to use it:

Search the internal company policy knowledge base for HR, security, compliance, and travel policy documents. Use this when the user asks about company-specific policy information that may not be available from general knowledge.

The model uses descriptions as part of its decision process. Descriptions should include:

• The tool’s domain
• The type of input expected
• The type of result returned
• When the tool should be used
• Important limits or exclusions

Example:

{
  "name": "search_policy_documents",
  "description": "Search approved internal policy documents. Use this for company-specific HR, security, travel, and compliance questions. This tool does not search emails, chat messages, or external websites."
}

The exclusion sentence prevents misuse.

Parameter design

Parameters should be as narrow as possible while still solving the task. Avoid dumping everything into a generic string if the fields can be structured.

Weak schema:

{
  "type": "object",
  "properties": {
    "input": {
      "type": "string"
    }
  }
}

Better schema:

{
  "type": "object",
  "properties": {
    "employee_id": {
      "type": "string",
      "description": "The employee's internal ID."
    },
    "policy_area": {
      "type": "string",
      "enum": ["hr", "security", "travel", "compliance"],
      "description": "The policy area to search."
    },
    "query": {
      "type": "string",
      "description": "The user's policy question rewritten as a concise search query."
    }
  },
  "required": ["policy_area", "query"]
}

The better schema gives the model structure. The enum limits the policy area to valid values. The descriptions explain how to fill each field.

Use enums for controlled choices

Enums are valuable when the possible values are known. They reduce ambiguity and make downstream logic easier.

Example:

{
  "priority": {
    "type": "string",
    "enum": ["low", "medium", "high", "urgent"],
    "description": "The priority level based on business impact and urgency."
  }
}

Without an enum, the model might return critical, severe, important, or asap. Those may be understandable to a human but inconvenient for application code.

Use enums for:

• Status values
• Categories
• Priority levels
• Output formats
• Sort orders
• Known business types

Do not use enums when the real value space is open-ended, such as user names or search queries.

Required versus optional fields

Required fields should be truly required. If the model may not know a value, make the field optional or allow null.

For example, a contact extraction tool may not always have a phone number:

{
  "phone": {
    "type": ["string", "null"],
    "description": "The phone number if explicitly provided; otherwise null."
  }
}

This is better than forcing the model to invent missing information.

For action tools, required fields should include everything needed to execute safely. A create_calendar_event tool should require a title, start time, end time, and timezone. Otherwise the application may create bad events.

Avoid overloaded tools

An overloaded tool does too many things. For example:

manage_customer_account(action, customer_id, details)

This single tool might update an address, cancel a subscription, issue a refund, change a password, or delete an account. It is flexible but risky.

Prefer separate tools:

update_customer_address
create_refund_request
cancel_subscription_request
reset_customer_password

Separate tools allow separate descriptions, permissions, validation rules, logging, and confirmation requirements.

Example of a strong schema

Here is a tool for creating a support ticket draft:

{
  "type": "function",
  "function": {
    "name": "create_support_ticket_draft",
    "description": "Create a draft support ticket for human review. This tool does not submit or assign the ticket. Use it when the user wants to prepare a support issue from conversation details.",
    "parameters": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "description": "A concise ticket title under 80 characters."
        },
        "description": {
          "type": "string",
          "description": "A clear description of the issue, including symptoms, affected systems, and relevant context."
        },
        "priority": {
          "type": "string",
          "enum": ["low", "medium", "high", "urgent"],
          "description": "Priority based on user impact and urgency."
        },
        "category": {
          "type": "string",
          "enum": ["bug", "billing", "access", "feature_request", "other"],
          "description": "The best matching support category."
        },
        "requires_human_review": {
          "type": "boolean",
          "description": "Always true for this draft tool."
        }
      },
      "required": ["title", "description", "priority", "category", "requires_human_review"]
    }
  }
}

This schema is explicit about the tool’s limited authority. It creates a draft, not a submitted ticket.

Schema testing

Treat tool schemas as testable artifacts. Create example user requests and check whether the model selects the right tool and produces valid arguments.

Test cases should include:

• Normal requests
• Ambiguous requests
• Missing required information
• Requests that should not call a tool
• Requests that require a different tool
• Malicious or prompt-injection attempts
• Edge-case values

Example test:

{
  "user_request": "Please refund order ORD-12345 immediately.",
  "expected_behavior": "Do not call issue_refund directly. Create a refund request draft or ask for confirmation, depending on policy."
}

Practical takeaway

Tool schemas are prompts, contracts, and validation guides at the same time. A strong schema improves model behavior before your code ever runs. It also makes your application safer after the model produces a tool call.

Design schemas with the same care you would give to public API design: clear names, narrow purpose, typed parameters, meaningful constraints, and predictable outputs.