---
name: majiayu000/building-agent-tools
source: https://app.decimal.ai/s/majiayu000-building-agent-tools@1/SKILL.md
source_sha256: 342fb094ab62
---

# Building Tools for AI Agents

## Workflow

1. **Define Purpose**
   - Identify what agents need to accomplish with this tool
   - Determine if existing tools can be consolidated
   - Plan the tool's interface for agent consumption

2. **Design Interface**
   - Choose descriptive, namespaced tool names
   - Define parameters with clear types and descriptions
   - Design output format for maximum signal, minimum tokens

3. **Implement**
   - Build with token efficiency in mind
   - Add pagination, filtering, sensible defaults
   - Return semantic identifiers, not raw IDs

4. **Validate**
   - Test with real agent workflows
   - Check token consumption patterns
   - Verify error messages guide agents toward solutions

## Design Principles

**Tool Consolidation**
- More tools don't lead to better outcomes
- Combine related operations into single tools
- Example: `schedule_event` that checks availability AND creates event
- Avoid simple CRUD-style tools that require multiple calls

**Namespacing**
- Prefix related tools with service name: `asana_projects_search`, `asana_users_search`
- Group by domain to help agents distinguish functionality
- Use consistent naming patterns across tool families

**Meaningful Context**
- Return high-signal information, not raw data dumps
- Resolve cryptic UUIDs to human-readable identifiers
- Include `response_format` parameter (concise/detailed) for flexibility
- Surface relevant metadata agents need for next steps

**Token Efficiency**
- Implement pagination with sensible defaults
- Add filtering parameters to reduce unnecessary data
- Truncate large responses intelligently
- Prefer structured output over verbose prose

**Tool Descriptions**
- Invest heavily in clear, explicit descriptions
- Describe what the tool does, when to use it, and what it returns
- Include parameter constraints and valid values
- Small description improvements yield large performance gains

## Anti-Patterns

- Creating many granular tools instead of consolidated operations
- Returning raw IDs that agents can't interpret
- Omitting pagination on potentially large result sets
- Vague tool descriptions that leave agents guessing
- Error messages that don't help agents recover
- Requiring agents to make multiple calls for common workflows

## MCP-Specific Patterns

**Tool Registration**
- Use descriptive `name` and `description` in tool schema
- Define `inputSchema` with JSON Schema for parameters
- Mark required vs optional parameters explicitly

**Response Format**
- Return structured JSON for predictable parsing
- Include success/error indicators
- Provide actionable error messages