Skip to content
Quantoros

How do you design and define tools for an AI agent?

LLM & AILevel: IntermediateTool Use & MCP

How do you design and define tools for an AI agent?

Hints
  • Identify the stage: pretraining, adaptation, generation or evaluation.
  • Name the inputs, constraints and a case where the approach fails.

Answer

Good tool design determines agent quality. Principles:

1. Single responsibility: each tool does exactly one thing. Not search_and_analyze(), but search() and analyze() separately.

2. Descriptive names and docstrings: the model selects tools based on the description. Be explicit about when to use the tool and what it returns.

3. Structured inputs/outputs: use typed schemas (Pydantic, JSON Schema). Validation prevents the model from passing wrong parameter types.

4. Fail informatively: return structured error messages the model can reason about, not stack traces.

5. Idempotency for safe tools: read operations should always be safe to retry. Distinguish read from write tools clearly.

@tool
def search_knowledge_base(query: str, top_k: int = 5) -> list[dict]:
    """
    Search the internal knowledge base for information relevant to the query.
    Use this when you need factual information about company products, policies, or procedures.
    Returns a list of relevant document chunks with source metadata.
    Do NOT use this for real-time data like stock prices or weather.
    """

Source and licence: JustInCache & contributors — Awesome AI Interviews · Apache-2.0

Related questions