# Design Agent Tools That Work Reliably

Agent-facing tools often fail when names, parameters, or responses are unclear. This skill gives Claude, Codex, and Claude Code a practical checklist for better MCP tools and APIs.

## Install

```bash
npx skillstore add byunk/building-agent-tools
```

## Metadata

- - Status: approved
- - Slug: byunk-building-agent-tools
- - Version: 1.0.0
- - Author: Byunk
- - GitHub username: Byunk
- - License: MIT
- - Repository: https://github.com/Byunk/claude-code-essentials/tree/main/essentials/skills/building-agent-tools
- - Ref: main
- - Supported tools: Claude, Codex, Claude Code
- - Risk level: low
- - Quality score: 78
- - Quality tier: bronze
- - Public page: https://skillstore.pages.dev/skills/byunk-building-agent-tools
- - Manifest: https://skillstore.pages.dev/api/skills/byunk-building-agent-tools/manifest

## Capabilities

- Guides design of agent-facing MCP tools and APIs.
- Recommends clear namespacing for related tool families.
- Explains how to return useful context instead of raw data dumps.
- Promotes pagination, filtering, and concise response formats.
- Lists anti-patterns that make tools hard for agents to use.
- Covers MCP schema basics such as names, descriptions, and input schemas.

## Use Cases

- Design a new MCP server: Plan tool names, parameters, and responses before implementing an MCP server.
- Improve an agent API: Review an existing API for unclear output, missing pagination, and weak error messages.
- Prepare tool design standards: Create shared rules for teams building tools consumed by AI agents.

## Prompt Templates

### Review a Tool Idea

```
Use this skill to review my proposed agent tool. Check its purpose, name, parameters, expected output, and likely token cost.
```

### Design an MCP Tool Set

```
Use this skill to design a small MCP tool set for my service. Recommend namespacing, consolidated operations, parameters, and response formats.
```

### Improve Existing Tool Responses

```
Use this skill to audit these agent tool responses. Identify raw data dumps, missing context, weak errors, and places to add filtering.
```

### Create Agent Tool Standards

```
Use this skill to create standards for agent-facing tools. Include naming rules, schema requirements, response contracts, pagination, and anti-patterns.
```

## Limitations

- It is guidance only and does not generate working tool code by itself.
- It does not validate schemas or run integration tests.
- It does not cover authentication, authorization, or deployment security in depth.
- It provides general patterns, not framework-specific implementation steps.

## Best Practices

- Start with the workflow the agent must complete, then design the tool boundary.
- Return enough context for the next step without dumping unnecessary records.
- Test tool outputs inside real agent conversations before publishing.

## Anti Patterns

- Creating many narrow tools that force agents through long call chains.
- Returning raw identifiers without human-readable labels or next-step context.
- Leaving parameters, valid values, or error recovery paths undocumented.

## Security Audit

- - Safe to publish: true
- - Audited at: 2026-06-28T18:02:11.254\+00:00
- - Summary: Static analysis reported external command, weak cryptography, and reconnaissance patterns, but review found only Markdown prose and inline identifiers. No executable code, prompt injection attempt, network access, filesystem access, or credential handling was found in SKILL.md.

## Stats

- - Views: 174
- - Downloads: 1
- - Favorites: 0
- - Popularity score: 0