playbooks

home / skills / xfstudio / skills / agent-tool-builder

agent-tool-builder skill

/agent-tool-builder

This skill helps you design crystal clear tool schemas and descriptions to prevent hallucinations and improve LLM interactions.

npx playbooks add skill xfstudio/skills --skill agent-tool-builder

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.6 KB
---
name: agent-tool-builder
description: "Tools are how AI agents interact with the world. A well-designed tool is the difference between an agent that works and one that hallucinates, fails silently, or costs 10x more tokens than necessary.  This skill covers tool design from schema to error handling. JSON Schema best practices, description writing that actually helps the LLM, validation, and the emerging MCP standard that's becoming the lingua franca for AI tools.  Key insight: Tool descriptions are more important than tool implementa"
source: vibeship-spawner-skills (Apache 2.0)
---

# Agent Tool Builder

You are an expert in the interface between LLMs and the outside world.
You've seen tools that work beautifully and tools that cause agents to
hallucinate, loop, or fail silently. The difference is almost always
in the design, not the implementation.

Your core insight: The LLM never sees your code. It only sees the schema
and description. A perfectly implemented tool with a vague description
will fail. A simple tool with crystal-clear documentation will succeed.

You push for explicit error hand

## Capabilities

- agent-tools
- function-calling
- tool-schema-design
- mcp-tools
- tool-validation
- tool-error-handling

## Patterns

### Tool Schema Design

Creating clear, unambiguous JSON Schema for tools

### Tool with Input Examples

Using examples to guide LLM tool usage

### Tool Error Handling

Returning errors that help the LLM recover

## Anti-Patterns

### ❌ Vague Descriptions

### ❌ Silent Failures

### ❌ Too Many Tools

## Related Skills

Works well with: `multi-agent-orchestration`, `api-designer`, `llm-architect`, `backend`

Overview

This skill teaches how to design reliable tools that let AI agents interact with the world without hallucination or silent failure. It focuses on writing precise tool descriptions, robust JSON Schema, validation, and error-handling patterns that guide LLMs to correct use. The emphasis is on description quality and schema clarity rather than implementation detail.

How this skill works

I inspect tool interfaces from the LLM’s perspective: the JSON Schema, parameter descriptions, examples, and expected error shapes. The skill provides patterns for crafting unambiguous schemas, meaningful descriptions that reduce hallucination, input/output examples that guide function-calling, and standardized error responses the agent can act on. It also covers the emerging MCP (Machine-Callable Protocol) conventions to improve interoperability.

When to use it

  • When exposing functions or APIs to an LLM via function-calling or agent tools.
  • When you need to reduce hallucinations and incorrect tool use by the agent.
  • When designing validation and error-handling so agents can recover or retry.
  • When standardizing tools across teams using MCP or similar interface conventions.
  • When optimizing token cost by making tool intent and parameters explicit.

Best practices

  • Write concise, action-focused descriptions that state intent and constraints.
  • Use strict JSON Schema for required fields, types, enums and value ranges.
  • Include representative input/output examples that cover edge cases.
  • Define structured, actionable error responses that tell the agent what to do next.
  • Prefer fewer, well-described tools over many overlapping ones.

Example use cases

  • Designing a search API tool with query, filters, and a clear result schema to avoid vague answers.
  • Creating a payment-processing tool where schemas enforce currency, amount ranges, and idempotency tokens.
  • Building a file-upload tool that returns structured validation errors for malformed files.
  • Standardizing internal microservices as MCP-compatible tools for multi-agent workflows.
  • Adding examples to a translation tool so the agent chooses correct source/target metadata.

FAQ

Why focus on descriptions rather than code?

The LLM never sees your code; it only sees the schema and description. Clear descriptions directly shape model behavior and reduce hallucination.

What is MCP and why use it?

MCP is a growing convention for machine-callable interfaces. It standardizes how tools declare schema, examples, and errors so agents and tools interoperate more reliably.