# Design Reliable Agent Tools

Ambiguous tools cause routing errors, malformed calls, and failed recovery. This skill provides practical patterns for clear schemas, descriptions, responses, and tool catalogs.

## Install

```bash
npx skillstore add muratcankoylan/tool-design
```

## Metadata

- Status: approved
- Slug: muratcankoylan-tool-design
- Skillstore revision: r2
- Version status: missing
- Tree hash: 761f0ab8cac01b9a135b9e78a48100c00d89f3f3028188ab34dd84f72c4cfb32
- Author: muratcankoylan
- GitHub username: muratcankoylan
- License: MIT
- Repository: https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering/tree/main/skills/tool-design
- Ref: 02be9409c79ca1183f7844009c14d9df684d0cf9
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: scripts, external\_commands, network
- Quality score: 80
- Quality tier: silver
- Public page: https://skillstore.pages.dev/skills/muratcankoylan-tool-design
- Manifest: https://skillstore.pages.dev/api/skills/muratcankoylan-tool-design/manifest

## Capabilities

- Structures tool descriptions around purpose, activation conditions, inputs, outputs, and errors.
- Builds in-memory tool specifications with parameters, return metadata, triggers, examples, and error definitions.
- Renders structured Markdown descriptions from tool specifications.
- Scores descriptions for clarity, completeness, accuracy, actionability, and naming consistency.
- Creates recoverable error-message templates for validation, missing records, and rate limits.
- Guides MCP namespacing, tool consolidation, response formats, and sandboxed architectural reduction.

## Use Cases

- Define a new agent tool: Create a complete description, schema, response shape, and recovery contract before implementation.
- Audit an MCP catalog: Identify overlapping purposes, naming collisions, inconsistent parameters, and unclear selection guidance.
- Improve failed tool calls: Use observed failures to clarify descriptions, constraints, examples, and retry guidance.

## Prompt Templates

### Rewrite one tool description

```
Rewrite this tool description. State what it does, when to use it, accepted inputs, returned data, and recoverable errors: {description}
```

### Design a complete tool contract

```
Design an agent tool for {workflow}. Include a verb-noun name, typed parameters, defaults, response formats, examples, errors, and retry guidance.
```

### Audit a tool catalog

```
Audit these tools for overlapping activation scenarios, inconsistent names, schema conflicts, namespace collisions, missing errors, and oversized responses: {catalog}
```

### Evaluate architectural reduction

```
Compare specialized tools with a sandboxed primitive-tool design for {system}. Assess safety boundaries, routing accuracy, token cost, maintenance, and evaluation criteria.
```

## Limitations

- The evaluator uses simple text heuristics and does not measure real agent success.
- The utility does not register tools, run MCP servers, or call external services.
- Generated descriptions still require review against the implemented API behavior.
- Command-tool examples require a correctly isolated sandbox and separate security controls.

## Best Practices

- Describe purpose, activation conditions, parameters, returns, and errors as one self-contained contract.
- Use consistent verb-noun names, parameter terms, namespaces, and response fields across the catalog.
- Test representative requests and revise descriptions using observed routing and call failures.

## Anti Patterns

- Do not publish vague descriptions that force the agent to guess scope or input formats.
- Do not create overlapping narrow tools when one workflow tool has a clearer purpose.
- Do not expose unrestricted command execution without isolation, least privilege, and explicit safety controls.

## Security Audit

- Audited at: 2026-08-09T10:00:37.674\+00:00
- Summary: All 49 static findings are false positives from documentation markup, ordinary prose, or sandboxed command examples. The Python utility performs no network or process execution.

## Stats

- Views: 229
- Downloads: 14
- Favorites: 0
- Popularity score: 0