agent-tool-builder

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.

Quality

32%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/antigravity-awesome-skills/skills/agent-tool-builder/SKILL.md

Quality

Content

42%Scale 1-3

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill excels at actionability with rich, executable code examples across multiple frameworks and languages, making it genuinely useful for building agent tools. However, it suffers significantly from verbosity — it's a monolithic wall of content that mixes metadata, principles, validation rules, and detailed implementation patterns without any progressive disclosure or external references. The workflow for actually building a tool from scratch is implicit rather than explicitly sequenced with validation checkpoints.

Suggestions

Move detailed pattern implementations (MCP server, tool runner, parallel execution, error handling) into separate referenced files (e.g., PATTERNS.md, MCP.md, ERROR_HANDLING.md) and keep SKILL.md as a concise overview with links.

Remove metadata sections (Capabilities, Scope, When to Use, Limitations, Collaboration, Related Skills) from the body content — these belong in YAML frontmatter or a separate metadata file.

Add an explicit end-to-end workflow: 'Design schema → Write descriptions → Implement with error handling → Validate schema → Test with LLM → Iterate' with clear checkpoints at each stage.

Trim explanatory text that Claude already knows (e.g., 'MCP is Anthropic's open standard for connecting AI agents to external systems', basic error category lists, what enums are) to reduce token usage by ~30-40%.

Dimension	Reasoning	Score
Conciseness	The skill is extremely verbose at ~400+ lines. It explains concepts Claude already knows (what JSON Schema is, what MCP is, basic error handling categories), includes unnecessary metadata sections (Capabilities, Scope, When to Use, Limitations) that belong in frontmatter not body content, and repeats similar patterns multiple times. The 'Validation Checks' section reads like linter rules rather than actionable guidance. Significant token waste throughout.	1 / 3
Actionability	The skill provides extensive, concrete, executable code examples across Python and TypeScript. Tool schemas are complete JSON with realistic data, the error handling pattern includes a full dataclass implementation, MCP server code is copy-paste ready, and the parallel execution pattern shows both correct and incorrect approaches. Very high actionability.	3 / 3
Workflow Clarity	The skill covers multiple patterns but lacks a clear sequential workflow for building a tool end-to-end. There's no explicit 'design → implement → validate → test with LLM' workflow with checkpoints. The validation checks section lists rules but doesn't integrate them into a step-by-step process. The error handling pattern shows good recovery logic within individual tools, but the overall tool-building process lacks validation gates.	2 / 3
Progressive Disclosure	Everything is in a single monolithic file with no references to supporting documents. The content covers schema design, input examples, error handling, MCP, tool runners, and parallel execution all inline — easily 400+ lines that would benefit from being split into separate reference files. No bundle files exist to offload detailed patterns. The metadata sections (Capabilities, Scope, Delegation Triggers, When to Use, Limitations) further bloat the body.	1 / 3
	Total	7 / 12 Passed

Description

22%Scale 1-3

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This description reads more like a course syllabus tagline than a functional skill description. It leads with motivational framing ('A well-designed tool is the difference between...') rather than concrete capabilities, lacks any 'Use when...' trigger guidance, and fails to enumerate specific actions the skill enables. The description would benefit significantly from listing concrete actions and adding explicit trigger conditions.

Suggestions

Replace the motivational opening with concrete actions, e.g., 'Designs tool schemas, writes parameter descriptions, implements error handling, and optimizes token usage for AI agent tools.'

Add an explicit 'Use when...' clause, e.g., 'Use when designing function-calling tools, MCP tools, API tool definitions, or when the user asks about tool schemas, parameter validation, or agent tool integration.'

Remove the subjective/marketing language ('the difference between an agent that works and one that hallucinates') and use third-person declarative voice describing capabilities.

Dimension	Reasoning	Score
Specificity	The description uses vague, abstract language like 'covers tool design from schema to error handling' without listing concrete actions. It reads more like a marketing pitch than a capability description. No specific actions like 'create tool schemas', 'validate parameters', or 'generate error handlers' are mentioned.	1 / 3
Completeness	The 'what' is extremely vague ('covers tool design from schema to error handling') and there is no 'when' clause or explicit trigger guidance. The first two sentences are motivational fluff rather than functional description. Missing a 'Use when...' clause caps this at 2, but the weak 'what' brings it to 1.	1 / 3
Trigger Term Quality	Contains some relevant keywords like 'tool design', 'schema', 'error handling', 'AI agents', and 'tokens', but these are somewhat technical and may not match how users naturally phrase requests. Missing common variations like 'function calling', 'API tools', 'tool definitions', 'MCP tools'.	2 / 3
Distinctiveness Conflict Risk	The focus on 'tool design' for AI agents provides some specificity, but phrases like 'schema' and 'error handling' could overlap with general API design or coding skills. The domain is somewhat identifiable but not sharply delineated.	2 / 3
	Total	6 / 12 Passed

Validation

81%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 9 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (715 lines); consider splitting into references/ and linking	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	9 / 11 Passed

Repository: popey/claude-code-skills
Path: plugins/antigravity-awesome-skills/skills/agent-tool-builder/SKILL.md
Commit: a5a6601

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.