Defining tool schemas and descriptions in Agentic AI - Deep Dive

Overview - Defining tool schemas and descriptions

What is it?

Defining tool schemas and descriptions means creating clear, structured outlines that explain what a tool does, what inputs it needs, and what outputs it produces. These schemas act like blueprints that help AI systems understand how to use different tools correctly. Descriptions add human-friendly explanations to make the tool’s purpose and usage easy to grasp. Together, they guide AI agents to interact with tools effectively and safely.

Why it matters

Without clear tool schemas and descriptions, AI systems might misuse tools, causing errors or unexpected results. This can lead to wasted time, wrong decisions, or even safety risks in real-world applications. Well-defined schemas ensure AI agents know exactly how to call a tool, what data to provide, and what to expect back, making AI more reliable and trustworthy. This clarity also helps developers maintain and improve AI systems faster.

Where it fits

Before learning this, you should understand basic AI agent concepts and how AI interacts with external tools or APIs. After mastering tool schemas, you can explore advanced AI agent design, multi-tool coordination, and safety mechanisms for AI tool usage.

Mental Model

Core Idea

A tool schema is a precise recipe that tells an AI exactly how to prepare inputs, use a tool, and interpret its outputs.

Think of it like...

Defining tool schemas is like writing a clear recipe for a cooking robot: it needs to know the ingredients (inputs), the steps to cook (tool usage), and how the final dish should look or taste (outputs).

┌───────────────┐
│   Tool Schema │
├───────────────┤
│ Inputs       │
│ - Type       │
│ - Format     │
├───────────────┤
│ Description  │
│ - Purpose   │
│ - Usage     │
├───────────────┤
│ Outputs      │
│ - Type       │
│ - Format     │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

What is a Tool Schema?

Concept: Introduce the idea of a tool schema as a structured definition for AI tools.

A tool schema is like a form that lists what a tool needs to work and what it gives back. It includes the names and types of inputs, a description of what the tool does, and the expected outputs. This helps AI systems know how to use the tool without guessing.

Result

You understand that a tool schema is a clear, organized way to describe a tool’s inputs, outputs, and purpose.

Knowing that tool schemas are structured guides helps you see how AI can safely and correctly use many different tools.

2

Foundation

Why Descriptions Matter

Concept: Explain the role of human-readable descriptions in tool schemas.

Descriptions explain in simple words what the tool does and how to use it. They help both humans and AI developers understand the tool’s purpose and avoid mistakes. Without descriptions, even a correct schema can be confusing or misused.

Result

You realize that descriptions add clarity and reduce errors when AI or people use tools.

Understanding that descriptions bridge human and machine understanding prevents miscommunication and misuse.

3

Intermediate

Structuring Inputs and Outputs

🤔Before reading on: do you think inputs and outputs should be loosely or strictly defined in schemas? Commit to your answer.

Concept: Learn how to define inputs and outputs precisely with types and formats.

Inputs and outputs must be clearly typed (like text, number, or file) and formatted (like JSON or plain text). This strict definition ensures the AI sends the right data and knows what to expect back. For example, an input might be a 'string' called 'query', and the output might be a 'JSON object' with 'results'.

Result

You can create schemas that prevent errors by enforcing exact input and output formats.

Knowing that strict input/output definitions prevent confusion helps maintain reliable AI-tool interactions.

4

Intermediate

Using Schemas for AI Tool Calls

🤔Before reading on: do you think AI agents guess tool inputs or rely on schemas? Commit to your answer.

Concept: Show how AI agents use schemas to prepare and send tool calls.

AI agents read the schema to know what inputs to gather and how to format them. They then call the tool with these inputs and expect outputs as described. This process avoids trial-and-error and makes AI behavior predictable.

Result

You understand how schemas guide AI agents to interact with tools correctly every time.

Understanding this process reveals how schemas make AI tool usage systematic and error-resistant.

5

Intermediate

Common Schema Formats and Standards

Concept: Introduce popular formats like JSON Schema or OpenAPI used to define tool schemas.

Many tools use standard formats like JSON Schema or OpenAPI to describe inputs, outputs, and descriptions. These formats are machine-readable and widely supported, making it easier to share and validate schemas across systems.

Result

You can recognize and create schemas in common formats that AI systems expect.

Knowing standard formats helps you build interoperable AI tools and avoid reinventing the wheel.

6

Advanced

Handling Optional and Complex Inputs

🤔Before reading on: do you think all tool inputs must always be provided? Commit to your answer.

Concept: Learn how schemas define optional inputs and nested complex data.

Schemas can mark some inputs as optional, meaning the AI can skip them if not needed. They can also describe complex inputs like lists or objects with nested fields. This flexibility allows tools to handle varied use cases without breaking.

Result

You can design schemas that are both precise and flexible for real-world tools.

Understanding optional and complex inputs prevents rigid schemas that limit AI tool usefulness.

7

Expert

Schema Evolution and Backward Compatibility

🤔Before reading on: do you think changing a tool schema breaks AI systems immediately? Commit to your answer.

Concept: Explore how schemas can change over time without breaking existing AI integrations.

In production, tool schemas evolve as tools improve. Experts design schemas to be backward compatible by adding new optional fields or versioning schemas. This careful evolution avoids breaking AI agents that rely on older schema versions.

Result

You understand best practices for maintaining and updating tool schemas safely in real-world AI systems.

Knowing schema evolution strategies helps prevent costly downtime and bugs in AI-tool ecosystems.

Under the Hood

Tool schemas work by defining a contract between the AI agent and the tool. At runtime, the AI uses the schema to validate inputs before sending them, ensuring they match expected types and formats. The tool processes the inputs and returns outputs structured as the schema specifies. This contract reduces errors and clarifies communication between AI and tools.

Why designed this way?

Schemas were designed to solve the problem of AI agents misusing tools due to unclear expectations. Early AI systems often guessed inputs or outputs, causing failures. Structured schemas provide a formal, machine-readable way to specify tool interfaces, improving reliability and enabling automation. Alternatives like informal documentation were too error-prone and not machine-friendly.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│   AI Agent    │──────▶│   Tool Schema  │──────▶│    Tool API   │
│ - Reads schema│       │ - Defines I/O  │       │ - Executes    │
│ - Validates   │       │ - Provides desc│       │ - Returns data│
└───────────────┘       └───────────────┘       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think tool schemas are only for humans to read, not machines? Commit yes or no.

Common Belief: Tool schemas are just documentation for humans to understand tools.

Reality: Tool schemas are primarily machine-readable contracts that AI agents use to validate and format data automatically.

Why it matters: Treating schemas as only human-readable leads to AI agents guessing inputs, causing errors and unreliable tool usage.

Quick: Do you think all inputs in a schema must always be provided? Commit yes or no.

Common Belief: Every input defined in a tool schema is mandatory for the tool to work.

Reality: Schemas can mark inputs as optional, allowing AI to skip them when not needed.

Why it matters: Assuming all inputs are mandatory can make AI agents provide unnecessary data or fail when optional inputs are missing.

Quick: Do you think changing a tool schema always breaks AI integrations immediately? Commit yes or no.

Common Belief: Any change to a tool schema breaks all AI systems using it.

Reality: Schemas can evolve with backward compatibility, allowing AI systems to continue working with older versions.

Why it matters: Believing schemas are fragile discourages improvements and causes unnecessary system freezes.

Quick: Do you think tool schemas define how the tool works internally? Commit yes or no.

Common Belief: Tool schemas describe the internal logic and algorithms of the tool.

Reality: Schemas only define inputs, outputs, and descriptions, not internal workings.

Why it matters: Confusing schemas with implementation details leads to overcomplicated schemas and misunderstanding of their purpose.

Expert Zone

1

Schemas often include metadata like version numbers and deprecation flags to manage tool lifecycle smoothly.

2

Some schemas support conditional inputs, where the presence of one input changes requirements for others, adding complexity.

3

In multi-tool AI systems, schemas enable automatic tool selection by matching input needs to tool capabilities.

When NOT to use

Tool schemas are less useful for very simple or one-off scripts where overhead is unnecessary. In such cases, direct code calls or informal documentation may suffice. Also, for highly dynamic tools with unpredictable inputs, schemas may be too rigid; flexible parsing or AI-driven input generation might be better.

Production Patterns

In production, tool schemas are stored in centralized registries or repositories for reuse. AI orchestration systems load schemas dynamically to validate and route tool calls. Versioning and backward compatibility are strictly enforced. Schemas are also used to generate user interfaces automatically for human-in-the-loop systems.

Connections

API Design

Tool schemas build on API design principles by defining clear interfaces for tools.

Understanding API design helps grasp why schemas must be precise, versioned, and documented for smooth AI-tool communication.

Data Validation

Schemas enforce data validation rules to ensure inputs and outputs meet expectations.

Knowing data validation concepts clarifies how schemas prevent errors and improve AI reliability.

Legal Contracts

Tool schemas act like contracts between AI and tools, specifying obligations and expectations.

Seeing schemas as contracts helps appreciate their role in preventing misunderstandings and ensuring dependable interactions.

Common Pitfalls

#1 Leaving input types vague or missing.

Wrong approach:

{ "inputs": { "query": {} }, "outputs": { "result": {} } }

Correct approach:

{ "inputs": { "query": { "type": "string" } }, "outputs": { "result": { "type": "string" } } }

Root cause:

Not specifying types causes AI to guess input formats, leading to errors.

#2 Forgetting to mark optional inputs.

Wrong approach:

{ "inputs": { "filter": { "type": "string" } } } // filter is optional but not marked

Correct approach:

{ "inputs": { "filter": { "type": "string", "optional": true } } }

Root cause:

Assuming all inputs are mandatory restricts AI flexibility and causes failures.

#3 Changing schema fields without versioning.

Wrong approach:

Modifying existing input names or types directly in the schema used by AI agents.

Correct approach:

Creating a new schema version with changes and keeping the old version intact.

Root cause:

Ignoring versioning breaks AI integrations relying on previous schema versions.

Key Takeaways

Tool schemas are structured blueprints that define exactly how AI agents should use tools.

Clear input and output definitions prevent errors and make AI-tool communication reliable.

Human-readable descriptions in schemas help avoid misunderstandings and misuse.

Schemas evolve carefully with versioning to keep AI systems stable over time.

Understanding schemas as contracts between AI and tools is key to building dependable AI applications.

Practice

1. What is the main purpose of defining a tool schema in agentic AI?

easy

A. To describe what the tool does and what inputs it needs

B. To write the tool's source code

C. To train the AI model

D. To store user data securely

Solution

1. Step 1: Understand the role of tool schemas

   Tool schemas explain what a tool does and what inputs it requires for proper use.

2. Step 2: Differentiate from other tasks

   Writing code, training models, or storing data are separate tasks not covered by schemas.

3. Final Answer:

   To describe what the tool does and what inputs it needs -> Option A

4. Quick Check:

   Tool schema = tool description + inputs [OK]

Hint: Schemas explain tool purpose and inputs clearly [OK]

Common Mistakes:

• Confusing schema with code implementation
• Thinking schema trains the AI
• Assuming schema stores data

2. Which of the following is the correct way to define a tool schema description in JSON format?

easy

A. {"name": search, "desc": "Finds info", inputs: {query: string}}

B. {"tool": search, description: Finds info, inputs: query string}

C. {"name": "search", "description": "Finds information", "inputs": {"query": "string"}}

D. {name: "search", description: "Finds information", inputs: {query: string}}

Solution

1. Step 1: Check JSON syntax correctness

   {"name": "search", "description": "Finds information", "inputs": {"query": "string"}} uses proper JSON with keys and string values quoted correctly.

2. Step 2: Verify key names and structure

   {"name": "search", "description": "Finds information", "inputs": {"query": "string"}} uses "name", "description", and "inputs" keys properly with correct value types.

3. Final Answer:

   {"name": "search", "description": "Finds information", "inputs": {"query": "string"}} -> Option C

4. Quick Check:

   Valid JSON with quoted keys and strings = {"name": "search", "description": "Finds information", "inputs": {"query": "string"}} [OK]

Hint: Look for quoted keys and string values in JSON [OK]

Common Mistakes:

• Missing quotes around keys or strings
• Using unquoted identifiers
• Incorrect key names or structure

3. Given this tool schema snippet:

{"name": "calculator", "description": "Performs math operations", "inputs": {"operation": "string", "x": "number", "y": "number"}}

What would be the expected output if the tool is called with inputs {"operation": "add", "x": 5, "y": 3}?

medium

A. 8

B. "add"

C. 53

D. Error: missing inputs

Solution

1. Step 1: Understand the tool schema inputs

   The tool expects an operation (like add) and two numbers x and y.

2. Step 2: Apply the operation to inputs

   Adding 5 and 3 results in 8 as output.

3. Final Answer:

   8 -> Option A

4. Quick Check:

   5 + 3 = 8 [OK]

Hint: Match inputs to operation and compute result [OK]

Common Mistakes:

• Returning operation string instead of result
• Concatenating numbers as strings
• Assuming missing inputs cause error

4. You have this tool schema:

{"name": "translator", "description": "Translates text", "inputs": {"text": "string", "target_lang": "string"}}

Which error is present in this schema?

medium

A. Description is too long

B. Name key is missing

C. Input types should be numbers

D. Missing closing brace for inputs object

Solution

1. Step 1: Check JSON syntax carefully

   The inputs object is opened but not closed with a } before the schema ends.

2. Step 2: Verify other keys

   Name key exists, description length is fine, input types as strings are correct.

3. Final Answer:

   Missing closing brace for inputs object -> Option D

4. Quick Check:

   Unclosed braces cause JSON errors [OK]

Hint: Count opening and closing braces carefully [OK]

Common Mistakes:

• Ignoring missing braces
• Thinking input types must be numbers
• Assuming description length matters

5. You want to define a tool schema for a weather forecast tool that takes a city name and date, and returns temperature and conditions. Which schema correctly describes this tool?

hard

A. {"name": "weather", "description": "Forecast tool", "inputs": {"city": "string"}, "outputs": {"temp": "string", "cond": "string"}}

B. {"name": "weather", "description": "Provides weather forecast", "inputs": {"city": "string", "date": "string"}, "outputs": {"temperature": "number", "conditions": "string"}}

C. {"name": "weather", "description": "Gives weather", "inputs": {"location": "string", "day": "date"}}

D. {"name": "weather", "inputs": {"city": "string", "date": "string"}}

Solution

1. Step 1: Check completeness of schema

   {"name": "weather", "description": "Provides weather forecast", "inputs": {"city": "string", "date": "string"}, "outputs": {"temperature": "number", "conditions": "string"}} includes name, description, inputs (city and date), and outputs (temperature and conditions) as required.

2. Step 2: Verify input and output types

   Inputs are strings (city, date), outputs are number and string, matching expected data.

3. Final Answer:

   {"name": "weather", "description": "Provides weather forecast", "inputs": {"city": "string", "date": "string"}, "outputs": {"temperature": "number", "conditions": "string"}} -> Option B

4. Quick Check:

   Complete schema with inputs and outputs = {"name": "weather", "description": "Provides weather forecast", "inputs": {"city": "string", "date": "string"}, "outputs": {"temperature": "number", "conditions": "string"}} [OK]

Hint: Include inputs and outputs with correct types [OK]

Common Mistakes:

• Omitting outputs section
• Using wrong input/output keys or types
• Leaving out description