ai-ml-build-agents-and-tools

name	ai-ml-build-agents-and-tools
description	Use when implementing agent loops, tool definitions, handoffs, manager-worker or multi-agent orchestration, context transfer, memory, MCP integrations, stopping conditions, and human checkpoints after agentic complexity has been justified.

Agents and Tools

First use ai-ml-build-llm-app-architecture to justify agency and orchestration. Apply ai-ml-build-ai-security to every tool and external context source.

Build one observable loop

Implement observe → decide → act → verify with explicit completion, failure, human-escalation, and maximum turn/time/cost/tool-call conditions. Feed each tool result back as environmental ground truth. Preserve a trace of model choice, tool request, validated arguments, result, state transition, and stop reason without logging secrets or unnecessary personal data.

Design tools as narrow contracts

• Name the action and domain unambiguously; describe when to use it, required input, effect, return, errors, idempotency, and limits.
• Prefer task-level tools with typed schemas over raw shell, SQL, HTTP, or generic “execute” access.
• Separate read from write and reversible from irreversible operations. Validate and authorize every call in application code; the model never grants itself permission.
• Return concise structured results with stable error codes and a corrective next step. Paginate or summarize large results and keep source identifiers for follow-up.
• Test descriptions and schemas through evals; a technically correct tool the model cannot select reliably is not usable.

Use MCP when multiple agent clients need a standard capability boundary or external context/tool provider. Use ordinary application functions when the capability is local to one system; protocol infrastructure is not automatically better architecture.

Add agents only for real separation

Prefer a manager using specialists as tools when one agent should own the user interaction and synthesis. Use handoffs when a specialist should own the next interaction and context. Define each agent's scope, tools, input/output contract, termination, and context budget. Do not split agents by fictional job titles when functions or prompts would express the same separation.

Minimize transferred context: task, constraints, relevant evidence, decisions, and expected output. Never rely on another agent inferring hidden state. Parallelize independent work only; reconcile conflicts explicitly before effects.

Completion gate

Every loop is bounded and traceable; every tool is least-privileged, typed, authorized, tested, and actionable on failure; every handoff has ownership and context contracts; high-risk effects pause for accountable human approval.