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