Tool Descriptions as Context

The Problem This Solves

Tool definitions are context: the model reads them to decide which tool to call, what arguments to pass, and what the result means. The quality of those definitions determines whether it gets any of that right.

Poor descriptions cause cascading failures: the model picks the wrong tool, calls the right tool with wrong arguments, or misses an opportunity to use a tool entirely. Each failed call wastes a turn, burns tokens, and often requires the user to intervene; in agentic loops, one vague description can derail a whole chain of tool calls.

How It Works

A tool definition has four parts, and the last two are where most teams underinvest. Start with a name that suggests purpose: search_knowledge_base is clear, while query_42 is not. Use the description to tell the model what the tool does, when to use it, and what it does not do. Treat parameters as Schema Steering: typed inputs with short descriptions constrain what the model can pass. Add a return description when one tool’s output feeds the next step, because the model needs to know what came back before it can plan around it.

The description is where most of the value lives. Compare:

# The model has to guess when to use this and what it covers
def search_documents(query: str):
    """Search for documents matching the query."""

# The model knows exactly when this is appropriate
def search_documents(query: str):
    """Search the internal knowledge base for policies,
    procedures, and FAQs. Use when the user asks about
    company processes or specific procedures. Returns
    top 5 results with excerpts. Does NOT search code
    repositories or customer data."""

The second version gives the model enough information to decide whether this tool fits the current task, instead of forcing it to guess from the name.

Example

A data analysis agent with three tools.

Bad definitions:

def query_db(sql): """Run a SQL query."""
def create_chart(data, type): """Create a chart."""
def send_email(to, subject, body): """Send an email."""

Here the model has to infer ordering, safety limits, and output shape from names that barely say anything.

Better definitions:

def query_db(sql):
    """Execute a read-only SQL query against the analytics
    database. Use for metrics, counts, aggregations, and
    lookups by ID. Do NOT use for writes or schema info
    (use describe_tables instead).
    Returns: JSON array of matching rows."""

def create_chart(data, chart_type):
    """Create a visualization from query results.
    Use after query_db when the user wants to see data
    visually. chart_type: 'bar' | 'line' | 'pie' | 'scatter'.
    Returns: URL to the generated chart image."""

def send_email(to, subject, body):
    """Send results to a user. Use ONLY after analysis is
    complete with results to share. Do not send test
    messages or debugging output.
    Requires: valid email, non-empty subject and body."""

Now the workflow is explicit: query first, chart if the user needs a visual, email only after there are results worth sending. These descriptions become a lightweight workflow specification embedded in the tool context.

When to Use

• Any agent or tool-using system
• Tools whose names do not fully capture scope and boundaries
• Tool sets where the model needs to choose between similar capabilities
• Systems where wrong tool calls are expensive, slow, unsafe, or hard to recover from

When Not to Use

• Standard library functions the model already understands well
• Tools so obvious and narrow that the name, parameters, and return type fully describe them
• Situations where a tool should not be visible to the model at all; hide it rather than writing a long warning

Related Patterns

• Select, Don’t Dump applies to tools too; if the model sees 30 tools when only 5 matter, selection suffers
• The Pyramid puts the most important information first: what the tool does and when to use it before parameter details
• Schema Steering constrains what the model can pass into each tool