How to Document Custom Tools for AI Agents in 2026: Complete Developer Guide

How to Document Custom Tools for AI Agents: A Complete Guide for Developers in 2026

Introduction

Building an AI agent is no longer only about writing a good system prompt.

Modern AI agents can search databases, read documents, create calendar events, send messages, retrieve customer records, update CRM systems, execute code, and interact with external APIs.

They accomplish these tasks through tools.

But simply connecting an API to an AI model does not mean the agent will use it correctly.

Imagine giving an AI agent these three tools:

search
get
update

A human developer might understand what they do because they built the system.

The AI agent does not have that background knowledge.

What does search search?

What can get retrieve?

What exactly can update modify?

Which parameters are required?

What happens if a record does not exist?

Does calling the tool make a permanent change?

This is why tool documentation is so important.

A well-documented tool helps the model understand:

What the tool does.
When it should be used.
When it should not be used.
Which arguments it accepts.
What each argument means.
Which values are valid.
What information it returns.
Whether it changes external data.
What errors may occur.
What permissions are required.

In this Answer Beam guide, we'll explain how to document custom tools for AI agents in a way that is useful both to developers and to the models calling those tools.

We'll also examine JSON schemas, tool descriptions, examples, API wrappers, Model Context Protocol (MCP), naming conventions, safety considerations, and common documentation mistakes.

The central principle is simple:

Treat tool documentation as part of your agent's interface—not as an afterthought.

What Is a Custom Tool for an AI Agent?

A custom tool is a function or external capability that an AI agent can invoke to perform a task outside normal text generation.

For example, an AI assistant could have access to:

search_products
get_order_status
create_support_ticket
send_customer_email
schedule_meeting
search_company_documents

Each tool gives the agent access to a specific capability.

Behind the tool might be:

A REST API.
A database.
A CRM.
An internal application.
A search engine.
A cloud service.
A file system.
Another AI model.
An MCP server.

The language model typically receives information describing the available tools and their accepted inputs.

It then decides whether a tool is appropriate for the user's request and, when applicable, supplies structured arguments.

Why Does Tool Documentation Matter?

AI agents make decisions based on the context developers provide.

Poor descriptions create ambiguity.

Suppose you define this tool:

Name: find_customer

Description:
Find customer.

That description leaves many questions unanswered.

Can it search by email?

Can it search by phone number?

Does it return multiple customers?

Does it perform fuzzy matching?

Should the model use it before updating an account?

Now consider:

Name: find_customer

Description:
Search customer records by email address, phone number,
or customer ID. Use this tool when the user wants to
locate an existing customer account. This tool only
retrieves records and does not modify customer data.

The second description gives the agent substantially more context.

It explains both capability and boundaries.

Clear, explicit instructions and context are generally important for reliable agent behavior; current agent-oriented prompting guidance likewise emphasizes specificity about desired actions and tool use. Claude Platform Docs

Tool Documentation Has Two Audiences

When documenting an AI tool, remember that you are often writing for two different audiences.

Audience 1: Developers

Developers need information such as:

Authentication.
API endpoints.
Parameter types.
Response schemas.
Error codes.
Rate limits.
Dependencies.
Environment variables.
Permissions.
Version history.

Audience 2: The AI Agent

The model needs a different kind of information.

It needs to understand:

What the tool accomplishes.
When to call it.
Which tool to choose when several look similar.
What arguments to provide.
Which information it must obtain first.
Whether the action is read-only or destructive.
What to do with the returned information.

Good documentation should support both audiences without confusing them.

The 10 Essential Parts of AI Tool Documentation

A practical tool specification can contain these elements:

Component	Purpose
Tool name	Identifies the capability
Description	Explains what it does
Use cases	Explains when to call it
Non-use cases	Explains when not to call it
Input schema	Defines accepted arguments
Parameter descriptions	Explains each input
Output	Explains returned information
Errors	Describes possible failures
Permissions	Defines access requirements
Examples	Demonstrates correct usage

Let's examine each one.

1. Give Every Tool a Clear Name

The tool name should communicate its purpose immediately.

Poor Names

do_search
tool1
process
execute
data
action

These names provide little semantic information.

Better Names

search_products
get_customer_profile
create_invoice
cancel_order
search_knowledge_base
schedule_meeting

These names combine an action with an object.

A useful naming pattern is:

verb + noun

Examples:

search_orders
get_order
update_order
cancel_order

This also makes related tools easier to distinguish.

2. Write a Precise Tool Description

The description is one of the most important pieces of documentation.

Avoid writing:

Gets information.

Instead, explain the capability.

For example:

Retrieve the current status and delivery information for
an existing customer order using its unique order ID.
This tool is read-only and does not modify the order.

Now the model knows:

It retrieves an order.
An order ID is needed.
It can return delivery information.
It does not modify anything.

Useful Tool Description Formula

Try:

Action + Object + When to Use + Important Limitation

Example:

Search the product catalog by keyword, category, brand,
or SKU. Use this tool when the user wants to discover
products but does not know the exact product ID.
This tool only searches the catalog and does not place orders.

That is much more informative than:

Search products.

3. Explain When the Agent Should Use the Tool

Tool descriptions should help the agent make decisions.

Suppose you provide two tools:

search_orders
get_order

Without further explanation, the model might confuse them.

Document them differently.

search_orders

Search for orders when the exact order ID is unknown.
Supports lookup using available customer or order-related
search criteria.

get_order

Retrieve one specific order when its exact order ID is known.

The distinction helps the agent choose the appropriate tool.

4. Explain When NOT to Use the Tool

This is particularly useful when several tools overlap.

For example:

Tool: search_web

Use when:
The user needs current public information from the web.

Do not use when:
The answer should come from the company's internal
knowledge base or private customer records.

Negative guidance can reduce inappropriate tool selection.

Another example:

Tool: send_email

Use when:
The user has explicitly requested that an email be sent.

Do not use when:
The user only asks you to draft, rewrite, or review an email.

The difference is important because one action changes the external world while the other does not.

5. Define a Clear Input Schema

AI tools commonly use structured inputs.

JSON Schema or a similar schema system can describe those inputs.

For example:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "Unique ID of the order to retrieve."
    }
  },
  "required": ["order_id"]
}

This tells the model that the tool expects an object containing an order_id string.

Why Schemas Matter

Schemas help constrain tool calls.

Instead of the model producing:

Please get order ABC123.

it can generate structured arguments such as:

{
  "order_id": "ABC123"
}

The application can then validate those arguments before executing the underlying function.

6. Document Every Parameter Clearly

Parameter descriptions should explain meaning, not simply repeat the parameter name.

Weak Example

{
  "email": {
    "type": "string",
    "description": "Email"
  }
}

Better Example

{
  "email": {
    "type": "string",
    "description": "Customer email address used to search for an existing account."
  }
}

The second version explains why the parameter exists.

Example With Several Parameters

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Keywords describing the products to search for."
    },
    "category": {
      "type": "string",
      "description": "Optional product category used to narrow the search."
    },
    "max_results": {
      "type": "integer",
      "description": "Maximum number of matching products to return.",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": ["query"]
}

Notice that each parameter has a specific purpose.

7. Use Enums When Only Certain Values Are Valid

If a parameter accepts only a fixed set of values, document that restriction.

For example:

{
  "status": {
    "type": "string",
    "enum": [
      "pending",
      "processing",
      "shipped",
      "delivered",
      "cancelled"
    ],
    "description": "Order status used to filter search results."
  }
}

This is better than accepting any arbitrary string and hoping the model chooses a valid value.

Enums can be particularly useful for:

Status values.
Sort order.
File formats.
Priority levels.
Supported regions.
Categories.
Operation types.

8. Document the Tool Output

Developers often spend significant effort describing inputs but barely explain the response.

The agent also needs to understand what the tool returns.

Suppose get_order_status returns:

{
  "order_id": "ORD-1048",
  "status": "shipped",
  "estimated_delivery": "2026-10-02",
  "tracking_number": "TRK839204"
}

Document those fields.

For example:

Returns:
- order_id: Unique order identifier.
- status: Current fulfillment status.
- estimated_delivery: Expected delivery date when available.
- tracking_number: Shipment tracking number when available.

This helps downstream logic.

The agent knows what information it can use in its response.

9. Document Errors and Failure Conditions

Tools do not always succeed.

An order might not exist.

An API could be temporarily unavailable.

Authentication may fail.

A parameter may be invalid.

Documentation should explain predictable failure states.

For example:

Possible errors:

NOT_FOUND
No order exists with the supplied order ID.

INVALID_ARGUMENT
One or more arguments do not meet the required format.

UNAUTHORIZED
The current user does not have permission to view the order.

SERVICE_UNAVAILABLE
The order service is temporarily unavailable.

Why Error Documentation Matters

Without clear errors, an AI agent may misinterpret a failure as an empty result.

That can lead to incorrect responses.

For example:

No matching records and database unavailable are very different situations.

The tool should make that distinction clear.

10. Include Realistic Examples

Examples help demonstrate the intended interface.

Current prompting guidance also emphasizes examples as a reliable way to improve consistency when they closely match real use cases. Claude Platform Docs

Consider this tool:

search_products

Example 1

User request:

Find waterproof backpacks under $100.

Tool call:

{
  "query": "waterproof backpack",
  "max_price": 100
}

Example 2

User request:

Show me black running shoes.

Tool call:

{
  "query": "running shoes",
  "color": "black"
}

Examples make parameter relationships easier to understand.

A Complete Example of Good AI Tool Documentation

Here is a more complete example.

Tool Name

search_customer_orders

Description

Search existing customer orders using an email address,
order status, or date range.

Use this tool when the exact order ID is unknown and the
user needs help locating one or more previous orders.

This tool is read-only and cannot modify or cancel orders.

Input Schema

{
  "type": "object",
  "properties": {
    "customer_email": {
      "type": "string",
      "description": "Email address associated with the customer's orders."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "processing",
        "shipped",
        "delivered",
        "cancelled"
      ],
      "description": "Optional order status filter."
    },
    "start_date": {
      "type": "string",
      "description": "Optional beginning of the order date range in YYYY-MM-DD format."
    },
    "end_date": {
      "type": "string",
      "description": "Optional end of the order date range in YYYY-MM-DD format."
    }
  },
  "required": ["customer_email"]
}

Returns

A list of matching orders containing:

- order_id
- order_date
- status
- total
- currency

Does Not

- Cancel orders.
- Update shipping information.
- Issue refunds.
- Modify customer accounts.

Example

{
  "customer_email": "customer@example.com",
  "status": "shipped"
}

This documentation gives the agent a much clearer operational picture.

Document Read-Only and Write Tools Differently

This distinction becomes especially important for autonomous agents.

Read Tool

get_customer_profile

It retrieves information but does not change anything.

Write Tool

update_customer_address

It modifies stored information.

Write tools deserve more explicit documentation.

For example:

Updates the shipping address for an existing customer.

This operation modifies customer data.

Use only when the user has clearly requested an address
change and the required customer and address information
has been obtained.

You may also implement application-level confirmation requirements for sensitive actions.

Document Side Effects

A tool's side effects should never be hidden.

Suppose this tool exists:

create_invoice

Calling it might:

Create a permanent accounting record.
Generate an invoice number.
Notify another system.
Trigger an email.

The documentation should explain relevant consequences.

For example:

Creates a new invoice in the billing system.

This is a write operation and creates a persistent financial
record. A successful call returns the new invoice ID.

Do not call this tool merely to calculate or preview an invoice.
Use the invoice preview tool for that purpose.

That last sentence prevents an especially dangerous mistake.

Separate "Preview" From "Execute"

A useful design pattern for consequential actions is to separate preparation from execution.

For example:

preview_refund
issue_refund

The first could calculate:

Refund amount.
Eligible items.
Applicable fees.
Payment method.

The second actually processes the refund.

Similarly:

draft_email
send_email

or:

calculate_shipping
purchase_shipping_label

This architecture can make the agent's choices easier to understand and control.

How to Document Tool Permissions

Not every user should be allowed to execute every action.

Your documentation should identify relevant permissions.

For example:

Tool: issue_refund

Required permission:
refund:create

Or:

Access:
Customer support managers and administrators only.

However, documentation alone is not security.

The backend must enforce authorization independently.

Never rely on the AI model to enforce access control.

How to Document Authentication

Developer-facing documentation should explain how the integration authenticates.

Common approaches include:

API keys.
OAuth.
Service accounts.
Short-lived tokens.
User-authorized credentials.

Avoid placing actual secrets inside model-visible tool descriptions.

Instead, document the mechanism separately.

Example:

Authentication:
OAuth 2.0

Required scope:
orders.read

Secrets should be handled by your application or secure infrastructure.

Tool Documentation for MCP Servers

The Model Context Protocol (MCP) is an open standard for connecting AI applications with external systems containing tools and data.

The current MCP TypeScript SDK describes MCP servers as exposing tools, resources, and prompts that compatible hosts can connect to. MCP TypeScript SDK

There is also an official MCP Registry for discovering published MCP servers. MCP Registry

A tool registered through an MCP server still needs meaningful metadata.

Conceptually, an MCP tool might resemble:

server.registerTool(
  "get-weather",
  {
    description: "Get the current weather for a specified city.",
    inputSchema: {
      city: z.string()
    }
  },
  async ({ city }) => {
    // Retrieve weather data
  }
);

The implementation details vary by SDK version, so developers should follow the current MCP SDK documentation rather than copying outdated examples.

MCP Documentation Should Explain

For every tool, document:

Tool name.
Purpose.
Input schema.
Output.
Errors.
Authentication.
Required permissions.
Side effects.
Examples.
Version information.

If the MCP server also exposes resources or prompts, document those separately rather than treating everything as a tool.

Tools, Resources, and Prompts Are Not the Same

In an MCP-style architecture, these concepts have different purposes.

Component	General Purpose
Tool	Performs an operation or computation
Resource	Makes data or content available
Prompt	Provides reusable prompt/workflow structure

For example:

Tool:
create_support_ticket

Resource:
support://policies/refunds

Prompt:
customer-refund-assistant

Choosing the appropriate primitive can make an integration easier to maintain.

Keep Tool Descriptions Focused

A tool description should be informative without becoming an entire developer manual.

Avoid putting unrelated information into the model-visible description.

For example, the model usually does not need to know:

This service was originally built in 2021 and migrated
from server A to server B...

That information may belong in internal developer documentation.

The model-visible description should focus on operational information that helps it decide whether and how to use the tool.

Use Consistent Terminology

Suppose one tool calls something:

customer_id

another calls it:

client_id

and another calls it:

user_reference

If all three represent the same concept, inconsistent naming creates unnecessary confusion.

Choose one canonical term.

For example:

customer_id

Use it consistently across:

get_customer
update_customer
list_customer_orders
create_customer_ticket

Consistency makes your entire tool ecosystem easier for humans and agents to understand.

Avoid Ambiguous Boolean Parameters

Consider:

{
  "active": true
}

What does true mean?

Active customers?

Activate the customer?

Only include active records?

A clearer parameter might be:

{
  "include_inactive_customers": false
}

Or use an enum:

{
  "account_status": "active"
}

The best option depends on the operation, but parameter names should make their meaning obvious.

Document Date and Time Formats

Dates cause frequent integration problems.

Instead of:

start_date: date

write:

start_date:
Beginning of the search period in YYYY-MM-DD format.

For timestamps, specify timezone expectations.

For example:

scheduled_at:
ISO 8601 timestamp including timezone offset.
Example: 2026-10-05T14:30:00+04:00

This prevents ambiguity between local time and UTC.

Document Units

Never leave measurement units unclear.

Bad:

distance: 50

Is that:

50 meters?
50 kilometers?
50 miles?

Better:

{
  "distance_km": 50
}

The same principle applies to:

price_usd
weight_kg
duration_seconds
temperature_celsius

Explicit units reduce errors.

What Should NOT Go Into Tool Documentation?

Avoid including:

API secrets.
Passwords.
Private tokens.
Unnecessary internal infrastructure details.
Huge unrelated manuals.
Contradictory instructions.
Outdated parameters.
Examples that no longer match the schema.

Documentation that is technically detailed but outdated can be worse than concise documentation that is correct.

Create One Source of Truth

One common engineering problem is maintaining the same information in several places.

For example:

API schema
README
developer portal
tool description
SDK comments

Eventually they become inconsistent.

Where practical, generate parts of your documentation from a canonical schema or source definition.

For example:

Canonical Tool Definition
          ↓
JSON Schema
          ↓
Developer Reference
          ↓
Agent Tool Metadata
          ↓
Automated Tests

Not every section can be generated automatically, but duplicated technical facts should be minimized.

Version Your Tools

Tools change over time.

Imagine changing:

search_products

so that a parameter previously named:

max_price

becomes:

price_max

Older clients may break.

Document:

Tool version.
Added parameters.
Removed parameters.
Deprecated fields.
Behavioral changes.
Migration instructions.

For larger integrations, maintain a changelog.

Test Documentation Like Code

Tool documentation should be tested against real agent behavior.

Create scenarios such as:

Test 1

User:

Find my last three orders.

Expected behavior:

Use search_orders.

Test 2

User:

Cancel order ORD-123.

Expected behavior:

Use the appropriate cancellation workflow rather than a read-only search tool.

Test 3

User:

What would my refund be?

Expected behavior:

Use preview_refund rather than issue_refund.

These tests help reveal ambiguous tool descriptions.

Common Documentation Mistakes

Mistake 1: Description Is Too Short

Search database.

Better: Explain what database information can be searched and when the tool should be used.

Mistake 2: Every Tool Sounds Similar

If five tools all say “Gets customer information,” the model has little basis for choosing correctly.

Better: Clearly distinguish their responsibilities.

Mistake 3: Parameters Have No Descriptions

A schema alone may not explain the semantic meaning of each field.

Better: Add concise parameter descriptions.

Mistake 4: Side Effects Are Hidden

A tool called process_order could do almost anything.

Better: State whether it creates, updates, charges, sends, deletes, or otherwise changes external state.

Mistake 5: No Error Documentation

The agent may confuse a system failure with an empty result.

Better: Define meaningful error states.

Mistake 6: Examples Don't Match the Schema

Examples are useless if they use deprecated or invalid parameters.

Better: Test documentation examples automatically when possible.

Mistake 7: Documentation Becomes Outdated

The API changes but the agent description does not.

Better: Version and review tool documentation alongside code.

A Reusable AI Tool Documentation Template

You can use this template when designing your own tools:

TOOL NAME
[verb_noun]

PURPOSE
What does this tool do?

WHEN TO USE
What user requests or agent situations require this tool?

WHEN NOT TO USE
Which similar situations require another tool?

INPUTS
Parameter:
Type:
Required:
Description:
Allowed values:
Format:
Example:

OUTPUT
What information does the tool return?

SIDE EFFECTS
Does it create, modify, send, purchase, delete, or otherwise
change external data?

PERMISSIONS
What authorization is required?

ERRORS
What predictable failure states can occur?

EXAMPLES
Provide realistic user request → tool call examples.

VERSION
Current version and important compatibility information.

This structure can be adapted to your architecture.

Why Production AI Agents Need Better Tool Documentation

Consider an e-commerce AI agent with these tools:

search_orders
get_order
update_order
cancel_order
preview_refund
issue_refund
send_customer_email

Technically, every tool may work perfectly.

But imagine a customer says:

“I don't want this order anymore.”

Should the agent immediately call cancel_order?

Not necessarily.

The order might already have shipped. The user may only be asking whether cancellation is possible. The application may require confirmation before a consequential action.

This demonstrates an important principle:

Tool documentation is not only API documentation. It is part of the agent's decision-making environment.

11. Write Tool Descriptions for Decisions, Not Just Definitions

A conventional API description might say:

cancel_order

Cancels an order.

Technically correct—but incomplete for an agent.

A better description would be:

cancel_order

Cancel an existing order that is eligible for cancellation.

Use this tool only when the user has clearly requested cancellation
of a specific order and the required order identifier is available.

This operation changes the order permanently and may trigger
downstream fulfillment updates.

Do not use this tool merely to determine whether an order can
be cancelled.

Notice the difference.

The description communicates:

Capability.
Preconditions.
Side effects.
Decision boundaries.
An important non-use case.

A Practical Formula for Excellent Tool Descriptions

A strong description can follow this structure:

Action + Scope + When to Use + Preconditions + Side Effects + When Not to Use

For example:

Search the company's internal knowledge base for documents
matching a natural-language query.

Use when answering questions that require information from
internal company documentation.

This operation is read-only.

Do not use it for current public internet information or
private customer account records.

The model now has a clear boundary around the tool.

12. Make Similar Tools Easy to Distinguish

One of the biggest problems in large agent systems is tool overlap.

Imagine these tools:

find_customer
get_customer
search_customers
lookup_customer

Their differences are not obvious.

Instead, design distinct responsibilities.

search_customers

Search customer records using partial or incomplete information.
May return multiple matching customers.

get_customer

Retrieve one customer record using an exact customer ID.
Returns a single customer when the ID exists.

Now the distinction is clear:

Don't know ID → search_customers

Know exact ID → get_customer

This is easier for both developers and agents.

13. JSON Schema Best Practices for AI Agent Tools

Structured schemas reduce ambiguity and make validation easier.

Consider this tool:

{
  "name": "search_products",
  "description": "Search the product catalog.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string"
      },
      "category": {
        "type": "string"
      },
      "max_price": {
        "type": "number"
      }
    },
    "required": ["query"]
  }
}

This works, but the model receives little semantic guidance.

A stronger version is:

{
  "name": "search_products",
  "description": "Search the product catalog when the user does not know the exact product ID. This tool is read-only.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Natural-language keywords describing the product the user wants."
      },
      "category": {
        "type": "string",
        "description": "Optional product category used to narrow the search."
      },
      "max_price": {
        "type": "number",
        "minimum": 0,
        "description": "Optional maximum product price in the catalog's configured currency."
      }
    },
    "required": ["query"],
    "additionalProperties": false
  }
}

The second schema communicates substantially more information.

Use Required Fields Carefully

Do not mark a field as required simply because it is convenient for your backend.

Ask whether the operation genuinely cannot proceed without it.

Suppose a search tool accepts:

query
category
brand
minimum_price
maximum_price

If only query is necessary, don't require every filter.

Overly strict schemas may force the model to invent information it does not have.

Use Enums for Closed Sets

Suppose an order tool accepts a status filter.

Instead of:

{
  "status": {
    "type": "string"
  }
}

prefer:

{
  "status": {
    "type": "string",
    "enum": [
      "pending",
      "processing",
      "shipped",
      "delivered",
      "cancelled"
    ],
    "description": "Optional order status used to filter results."
  }
}

This tells both the model and your validator which values are legitimate.

Avoid Unnecessary Schema Complexity

More structure is not always better.

For example, if the agent simply needs:

{
  "order_id": "ORD-58321"
}

there is little value in creating several nested objects around it.

Prefer the simplest schema that accurately represents the operation.

This improves readability, validation, debugging, and maintenance.

14. REST API Tools vs MCP Tools

AI agents can access external capabilities through different architectures.

Two common approaches are direct API wrappers and MCP servers.

REST API Wrapper

Your application may expose a function that internally calls:

GET /orders/{order_id}

The model does not necessarily need to know the endpoint.

Instead, it sees something like:

get_order

Your application translates the tool call into the API request.

MCP Server

With MCP, a server can expose tools and other capabilities through a standardized protocol.

Model Context Protocol documentation

The documentation principles remain similar.

The agent still needs clear information about:

What the tool does.
What inputs it expects.
What it returns.
What permissions apply.
Whether it changes anything.

MCP standardizes parts of the connection architecture; it does not remove the need for good tool design.

15. Document Read, Write, and Destructive Tools Differently

Not every tool deserves the same level of caution.

A useful internal classification is:

Tool Type	Example	Typical Risk
Read	`get_order`	Low
Search	`search_orders`	Low
Create	`create_ticket`	Medium
Update	`update_address`	Medium
Communication	`send_email`	Medium
Financial	`issue_refund`	High
Delete	`delete_account`	High

This does not mean every read operation is harmless—retrieved data can still be sensitive.

But the classification helps you design appropriate controls.

Document Consequential Actions Explicitly

For example:

delete_customer_account

Permanently deletes the specified customer account and associated
data according to the application's deletion policy.

This is a destructive operation.

Do not call it when the user is asking how deletion works,
asking what data would be deleted, or merely considering deletion.

That is much safer than:

Deletes user.

16. Use Preview → Confirm → Execute for Sensitive Actions

For consequential operations, consider separating inspection from execution.

For example:

preview_refund
issue_refund

The workflow becomes:

Customer Request
      ↓
Identify Order
      ↓
preview_refund
      ↓
Show Relevant Information
      ↓
Required Confirmation / Authorization
      ↓
issue_refund

This architecture can be applied to:

preview_invoice → create_invoice

calculate_shipping → purchase_shipping_label

preview_booking → confirm_booking

draft_message → send_message

Separating preparation from execution reduces ambiguity and makes authorization easier to implement.

17. Document Tool Confirmation Requirements

Suppose a tool sends a real email.

Its documentation might say:

send_email

Sends an email using the connected account.

This action communicates externally.

Use only when the application has established that sending
is authorized for the current request.

Required inputs:
recipient
subject
body

However, an important architectural principle applies:

Do not rely only on a natural-language tool description to enforce confirmation.

If confirmation is required, implement that requirement in your application or authorization layer.

18. Design Better Tool Outputs

Input schemas receive a lot of attention, but outputs are equally important.

Consider:

{
  "success": true,
  "data": "Done"
}

This tells the agent almost nothing.

A more useful response could be:

{
  "status": "success",
  "order_id": "ORD-58321",
  "order_status": "shipped",
  "tracking_number": "TRK-938473",
  "estimated_delivery": "2026-10-03"
}

Structured responses are easier for the agent to reason about.

Include Machine-Readable Status Information

A useful response pattern might be:

{
  "status": "success",
  "data": {},
  "error": null
}

A failed request might return:

{
  "status": "error",
  "data": null,
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "No order exists with the supplied order ID."
  }
}

The exact structure depends on your architecture, but consistency matters.

19. Distinguish Empty Results From Errors

This distinction is extremely important.

Imagine a search tool returns:

[]

That might mean:

Search completed successfully, but no records matched.

But if your API fails and also returns an empty array, the agent cannot tell the difference.

Instead, distinguish them.

Successful Search With No Matches

{
  "status": "success",
  "results": [],
  "result_count": 0
}

Failed Search

{
  "status": "error",
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The search service is temporarily unavailable."
  }
}

These situations should never be treated as equivalent.

20. Document Search Tools Carefully

Search tools are common in AI agents.

They may search:

Websites.
Documents.
Databases.
Products.
Emails.
CRM records.
Knowledge bases.

A useful search-tool description might be:

search_knowledge_base

Search the organization's internal knowledge base using a
natural-language query.

Use when the answer depends on internal documentation and the
relevant document is not already available in context.

Returns matching document excerpts and source identifiers.

This tool is read-only.

Do not use it for public web searches or customer account data.

This tells the agent what information source it is querying.

Document Search Result Limits

If the tool returns only the top ten results, say so.

For example:

Returns up to 10 results ordered by relevance.

Otherwise, an agent may incorrectly assume that ten returned records represent the entire dataset.

For pagination, document fields such as:

next_cursor
has_more
page_size

21. Document Database Tools

Direct database tools require particularly careful design.

Avoid exposing a generic tool like:

execute_sql

unless there is a strong reason and appropriate security architecture.

Where possible, expose narrow business operations:

get_customer
search_orders
list_open_invoices
update_shipping_address

instead of unrestricted database execution.

Why?

Because narrow tools make it easier to enforce:

Permissions.
Validation.
Audit logging.
Allowed operations.
Data boundaries.

The AI should receive only the capabilities it actually needs.

22. Document Email and Messaging Tools

Messaging tools change the external world because they communicate with other people.

A good email tool might be documented as:

send_customer_email

Send an email to a customer using the organization's
connected email account.

Required:
recipient_email
subject
body

Side effect:
The email is sent externally.

Returns:
message_id
sent_at
delivery_status when available.

You might separately provide:

draft_customer_email

if drafting and sending are different operations.

23. Document Calendar Tools

Calendar operations should clearly distinguish searching from creating.

For example:

find_calendar_events

versus:

create_calendar_event

For creation, document:

Event title.
Start time.
End time.
Timezone.
Participants.
Location.
Description.
Recurrence if supported.

Timezones deserve particular attention.

Instead of:

start_time: 3 PM

prefer an explicit format such as:

2026-10-12T15:00:00+04:00

when your interface requires ISO 8601 timestamps.

24. Document Payment Tools Conservatively

Payment operations are consequential.

Suppose an agent has:

create_payment
refund_payment

Documentation should explain:

Currency.
Amount units.
Payment identifier.
Authorization requirements.
Idempotency behavior.
Possible states.
Side effects.

For example:

refund_payment

Issues a refund against an existing eligible payment.

This is a financial write operation.

The amount is expressed in the smallest currency unit.
For USD, 1500 represents $15.00.

Do not call this tool to estimate refund eligibility.
Use preview_refund first.

Most importantly, backend authorization must determine whether the operation is permitted.

25. Explain Idempotency

Retries happen.

Networks fail.

Agents may encounter uncertain tool results.

For operations such as payments, bookings, orders, or ticket creation, duplicate execution can be a serious problem.

If supported, document idempotency behavior.

Example:

idempotency_key

Unique identifier for this operation.

Repeated requests with the same key should not create
duplicate transactions while the key remains valid.

Your backend—not the model—must enforce this behavior.

26. How to Reduce Incorrect Tool Selection

If an agent repeatedly selects the wrong tool, don't immediately assume the model is the problem.

Inspect the tool interface.

Ask:

Are the names distinct?
Are descriptions specific?
Do overlapping tools explain their differences?
Are non-use cases documented?
Are parameters understandable?
Are there too many similar tools?
Are examples representative?
Is relevant context missing?

Sometimes the best solution is not a longer prompt.

It is a better tool architecture.

Bad Tool Architecture

get_data
fetch_data
retrieve_data
search_data
query_data

Even excellent descriptions may struggle to compensate for unnecessary overlap.

Better Tool Architecture

search_customers
get_customer
search_orders
get_order
get_invoice

Each capability has a distinct purpose.

27. Don't Give Every Agent Every Tool

Suppose your system has 80 tools.

Does every agent need all 80?

Probably not.

A customer-support agent might need:

search_customers
get_order
search_help_center
create_support_ticket

A finance agent might need:

get_invoice
list_payments
preview_refund
issue_refund

Limiting tools by role can improve clarity and reduce unnecessary capability exposure.

This is the principle of least privilege applied to agent tooling.

28. Tool Versioning and Deprecation

Imagine you currently expose:

create_ticket_v1

Later you introduce a better schema.

Avoid silently changing behavior in ways that break clients.

Document the transition.

For example:

create_ticket_v1
Status: Deprecated

Replacement:
create_ticket_v2

Deprecation date:
2026-12-01

Provide migration information:

Changes in v2:
- priority is now an enum.
- customer_id replaces client_reference.
- response includes ticket_url.

29. Maintain a Tool Changelog

For larger systems, maintain a changelog.

Example:

Version 2.3
- Added optional language parameter to search_documents.
- Added INVALID_LANGUAGE error.

Version 2.2
- Added pagination to search_documents.

Version 2.1
- Improved document source metadata.

This helps developers understand why agent behavior may change after a deployment.

30. Test Tool Documentation With Agent Evaluations

Documentation should be evaluated like other parts of your software.

Create a test dataset containing realistic user requests.

For example:

User Request	Expected Tool
“Where is order 58321?”	`get_order`
“Find my recent orders.”	`search_orders`
“How much would I get back?”	`preview_refund`
“Refund this order.”	Authorized refund workflow
“Write an email about the delay.”	Drafting workflow
“Send this email to John.”	Sending workflow

Then evaluate whether the agent consistently selects the expected operation.

Test Negative Cases Too

Don't test only when tools should be called.

Also test when they should not be called.

Example:

User:

Explain your refund policy.

Expected behavior:

Do not issue a refund.

Retrieve policy information if needed.

Another example:

What happens if I delete my account?

Expected behavior:

Explain the consequences.

Do not call delete_account.

Negative tests are essential for consequential tools.

31. Test Argument Extraction

Correct tool selection is only half the problem.

The agent also needs to supply correct arguments.

Suppose the user says:

Find black running shoes below $120.

Expected arguments:

{
  "query": "running shoes",
  "color": "black",
  "max_price": 120
}

Your evaluation should verify:

Correct tool.
Correct arguments.
No invented arguments.
Correct units.
Correct date/time interpretation.
Required information present.

32. Test Tool Results Too

Suppose get_order returns:

{
  "status": "success",
  "order_status": "shipped"
}

The assistant should not tell the user:

Your order has been delivered.

Tool-result interpretation should therefore be part of your evaluation suite.

33. A Production-Ready Documentation Example

Let's combine the principles into one example.

Tool Name

preview_refund

Purpose

Calculate the currently eligible refund for an existing order
without issuing or processing the refund.

When to Use

Use when the user asks:

- whether an order is refundable;
- how much could be refunded;
- which items are eligible;
- what refund method would apply.

When NOT to Use

Do not use this tool to actually issue a refund.
Use issue_refund only after the application's required
authorization and confirmation conditions have been satisfied.

Input Schema

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "Unique identifier of the order to evaluate."
    },
    "item_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional IDs of specific order items to evaluate. Omit to evaluate all eligible items."
    }
  },
  "required": ["order_id"],
  "additionalProperties": false
}

Example Output

{
  "status": "success",
  "order_id": "ORD-58321",
  "eligible": true,
  "currency": "USD",
  "refund_amount": 74.99,
  "eligible_item_ids": [
    "ITEM-101",
    "ITEM-102"
  ],
  "refund_method": "original_payment_method"
}

Side Effects

None.

This is a read-only calculation.
No money is transferred and the order is not modified.

Possible Errors

ORDER_NOT_FOUND
The supplied order does not exist.

NOT_ELIGIBLE
The order exists but does not qualify for a refund.

UNAUTHORIZED
The current user cannot access this order.

SERVICE_UNAVAILABLE
Refund eligibility cannot currently be calculated.

Permissions

orders.read
refunds.preview

Example

User:

How much would I get back if I returned order ORD-58321?

Tool:

{
  "order_id": "ORD-58321"
}

This is much closer to production-ready documentation than:

preview_refund — checks refunds

Complete Custom Tool Documentation Template

Use this template for your own AI agent projects.

==================================================
TOOL NAME
==================================================

[verb_noun]

==================================================
SUMMARY
==================================================

One-sentence explanation of the capability.

==================================================
PURPOSE
==================================================

Explain exactly what the tool does.

==================================================
WHEN TO USE
==================================================

List the situations where the agent should call it.

==================================================
WHEN NOT TO USE
==================================================

List similar situations requiring another tool or no tool.

==================================================
INPUT SCHEMA
==================================================

For every parameter document:

Name:
Type:
Required:
Description:
Allowed values:
Format:
Units:
Default:
Example:

==================================================
OUTPUT
==================================================

Describe all important returned fields.

==================================================
SIDE EFFECTS
==================================================

State whether the operation:

- reads;
- creates;
- updates;
- deletes;
- sends;
- purchases;
- refunds;
- books;
- publishes;
- or changes external state in another way.

==================================================
AUTHENTICATION
==================================================

Describe the authentication mechanism without exposing secrets.

==================================================
PERMISSIONS
==================================================

List required scopes or roles.

==================================================
ERRORS
==================================================

Error code:
Meaning:
Suggested handling:

==================================================
RATE LIMITS
==================================================

Document relevant request or usage limits.

==================================================
IDEMPOTENCY
==================================================

Explain retry and duplicate-operation behavior when applicable.

==================================================
EXAMPLES
==================================================

Provide realistic:

User request → Tool call → Tool response

examples.

==================================================
VERSION
==================================================

Current version:
Introduced:
Deprecated:
Replacement:

==================================================
CHANGELOG
==================================================

Record meaningful interface and behavior changes.

AI Agent Tool Documentation Checklist

Before releasing a custom tool, verify the following:

Tool name clearly communicates its purpose.
Description explains what the tool actually does.
"When to use" guidance is included where useful.
Similar tools are clearly differentiated.
Non-use cases are documented where necessary.
Every important parameter has a description.
Required parameters are genuinely required.
Closed values use enums where appropriate.
Dates and timestamps have defined formats.
Measurement and currency units are explicit.
Outputs are documented.
Empty results are distinguishable from failures.
Errors have meaningful codes.
Side effects are explicit.
Permissions are documented.
Backend authorization is enforced.
Sensitive actions have appropriate safeguards.
Retry/idempotency behavior is defined when necessary.
Examples match the current schema.
Tool selection is covered by tests.
Argument extraction is tested.
Tool-result interpretation is tested.
Documentation is versioned.
Deprecated fields are identified.
No API keys or secrets appear in model-visible documentation.

10 Answer Beam Recommendations

1. Design Narrow Tools

Prefer:

get_order

over:

execute_any_business_operation

Smaller capabilities are easier to understand, secure, and test.

2. Make Tool Names Self-Explanatory

Use action-oriented names such as:

search_documents
create_ticket
update_customer

3. Document Decisions, Not Only APIs

Tell the agent when the tool is appropriate—not merely what endpoint sits behind it.

4. Clearly Mark Side Effects

If a tool sends, creates, purchases, deletes, publishes, or refunds something, say so explicitly.

5. Keep Schemas Simple

Avoid unnecessary nesting and ambiguous parameters.

6. Separate Preview and Execution

For consequential actions, separate informational operations from state-changing operations where appropriate.

7. Use Structured Errors

Make "nothing found" different from "service failed."

8. Enforce Security Outside the Model

Permissions, authentication, spending limits, and access controls belong in trusted application infrastructure.

9. Test With Real User Language

Users rarely speak in API terminology.

Test requests such as:

“Where's my package?”

rather than only:

“Retrieve order status using order ID.”

10. Treat Documentation as Code

Review, test, version, and maintain it alongside the implementation.

Frequently Asked Questions

1. What Is Tool Documentation for an AI Agent?

Tool documentation describes the external capabilities available to an AI agent and explains how those capabilities should be used.

It can include names, descriptions, schemas, outputs, errors, permissions, examples, and operational boundaries.

2. How Detailed Should an AI Tool Description Be?

It should be detailed enough for the model to distinguish the tool from alternatives and understand important limitations.

Avoid both extremes:

Too little:
"Searches stuff."

and several pages of irrelevant implementation history.

Prioritize operational information.

3. Should AI Tools Use JSON Schema?

Structured schemas are extremely useful because they define parameter names, types, requirements, allowed values, and validation constraints.

The exact schema format depends on the framework or protocol you're using.

4. What Is MCP for AI Agents?

The Model Context Protocol is an open protocol designed to connect AI applications with external capabilities and contextual data.

MCP can expose primitives such as tools, resources, and prompts.

Learn about Model Context Protocol

MCP does not eliminate the need for clear descriptions, schemas, security, and testing.

5. Should an AI Agent Be Allowed to Execute Destructive Tools?

That depends on the application and its risk controls.

Consequential operations require appropriate authorization, validation, application-level safeguards, and often confirmation or approval workflows.

Simply writing "be careful" in a prompt is not a sufficient security control.

6. How Can Developers Prevent AI Agents From Calling the Wrong Tool?

There is no single technique that guarantees perfect selection.

Reliability can be improved by combining:

Distinct tool names.
Clear descriptions.
Narrow responsibilities.
Explicit non-use cases.
Good schemas.
Limited tool availability.
Representative examples.
Authorization controls.
Automated evaluations.

When errors occur repeatedly, investigate both model behavior and tool design.

Final Example: From Poor Documentation to Strong Documentation

Poor

Tool:
send

Description:
Sends stuff.

Arguments:
to
text

Better

Tool:
send_customer_message

Description:
Send a text message to an existing customer through the
connected messaging service.

Use when the user has requested that a completed message
be sent to a specified customer.

This operation communicates externally and may not be
reversible.

Do not use when the user only asks to draft, rewrite,
translate, or review a message.

Arguments:

customer_id:
Unique identifier of the recipient customer.

message:
Final message text to send.

Returns:

message_id
sent_at
delivery_status when available.

The difference is not cosmetic.

The second version gives the agent enough information to make a substantially better tool-use decision.

Answer Beam Final Recommendation

When developers first build AI agents, they often focus heavily on the model.

But an agent's reliability also depends on the environment surrounding that model.

Poorly named functions, ambiguous schemas, overlapping capabilities, inconsistent errors, and undocumented side effects can make even a strong model difficult to operate reliably.

A better development process is:

Define Capability → Name Tool → Describe Decision Boundary → Design Schema → Document Output → Define Errors → Secure Action → Add Examples → Test Agent → Version Documentation

And remember:

If a human developer cannot quickly understand the difference between two tools, an AI agent may struggle too.

Conclusion

Custom tools transform an AI model from a system that primarily generates information into an application that can interact with external systems.

That capability makes documentation especially important.

Good AI tool documentation should tell an agent not only how to call a function, but also why, when, and under what conditions it should be called.

Clear names improve selection.

Structured schemas improve arguments.

Explicit outputs improve interpretation.

Documented side effects improve decision-making.

Backend permissions improve security.

Examples improve consistency.

And automated evaluations help developers discover problems before users encounter them.

Whether you're building a customer-support agent, research assistant, coding agent, e-commerce assistant, internal business agent, or MCP server, treat tool documentation as a first-class component of the system.

A powerful tool is useful only when the agent understands when and how to use it.

Waseem Uddin

I am a graphic designer, web designer and digital content creator with a strong interest in artificial intelligence, technology and digital productivity. I have been using Blogger since 2011 and created AnswerBeam to publish clear, practical and carefully researched guides that help readers understand technology, improve their digital skills and make informed decisions. Every AnswerBeam article is reviewed for clarity and accuracy, and important information is supported by reliable and official sources. My goal is to turn complicated topics into simple, useful guidance that readers can apply in real life.