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. 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

Quality

27%

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 ./.agent/skills/agent-tool-builder/SKILL.md

Quality

Content

22%

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

This skill is essentially a table of contents with a philosophical preamble but no actionable content. It lacks any concrete examples, executable code, or workflow guidance in the main file. The sub-skill references suggest good structural intent, but the body content alone provides almost nothing Claude could act on.

Suggestions

Add at least one complete, executable example of a well-designed tool schema (JSON Schema with descriptions) directly in the main SKILL.md as a quick-start reference.

Include a concrete workflow for designing a tool: e.g., 1) Define the schema, 2) Write descriptions, 3) Add input validation, 4) Test with example inputs, with validation checkpoints.

Remove the 'Capabilities' bullet list (it's just tags) and the philosophical preamble about LLMs not seeing code—Claude already knows this. Replace with actionable guidance.

Add a brief 'Common patterns' section with at least one good vs. bad tool description example inline, so the skill is useful even without accessing sub-skill files.

Dimension	Reasoning	Score
Conciseness	The introductory paragraphs explain concepts Claude already understands (LLMs only see schemas, not code; good descriptions matter more than implementation). The 'Capabilities' list is essentially tags that add no instructional value. However, it's not excessively verbose overall.	2 / 3
Actionability	There is no concrete code, no executable examples, no specific commands, and no actionable guidance. The content describes philosophy and links to sub-skills but provides zero copy-paste-ready instructions or schemas in the main file.	1 / 3
Workflow Clarity	There is no workflow, no sequenced steps, and no validation checkpoints. The skill doesn't describe any process for building, validating, or testing tools—it merely lists sub-skill references with no connecting workflow.	1 / 3
Progressive Disclosure	The skill does reference six sub-skill files with clear one-level-deep links, which is good structure. However, since no bundle files are provided, we can't verify these references exist, and the main file itself contains almost no substantive content—it's essentially an empty hub with no quick-start or overview material to stand on its own.	2 / 3
	Total	6 / 12 Passed

Description

32%

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

The description reads more like an introductory essay or blog post than a functional skill description for selection purposes. It is truncated (cuts off mid-sentence), lacks a 'Use when...' clause, and uses editorial commentary ('Key insight...') rather than concise, actionable language. While it touches on a specific domain (AI tool design, MCP), it fails to provide the structured triggers and concrete actions needed for reliable skill selection.

Suggestions

Add an explicit 'Use when...' clause with trigger terms like 'tool design,' 'function calling,' 'MCP server,' 'tool schema,' 'tool parameters,' or 'tool definitions.'

Replace the essay-style prose with concise, action-oriented language listing specific capabilities (e.g., 'Designs JSON Schema tool definitions, writes effective tool descriptions, implements MCP-compliant tool servers, handles tool validation and error responses').

Remove editorial commentary like 'Key insight:' and 'A well-designed tool is the difference between...' — these add no selection value and waste tokens.

Dimension	Reasoning	Score
Specificity	The description names the domain (tool design for AI agents) and mentions some actions like 'JSON Schema best practices, description writing, validation, and MCP standard,' but these are more like topic areas than concrete actions. It lacks specific verbs like 'create schemas,' 'validate inputs,' or 'generate MCP-compliant tool definitions.'	2 / 3
Completeness	The description covers 'what' (tool design topics) but completely lacks any 'Use when...' clause or equivalent explicit trigger guidance. There is no indication of when Claude should select this skill. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and since the 'what' is also somewhat vague and reads more like an essay than a skill description, this scores a 1.	1 / 3
Trigger Term Quality	Includes some relevant keywords like 'tool design,' 'JSON Schema,' 'MCP standard,' 'error handling,' and 'AI agents,' but misses common user phrasings like 'function calling,' 'tool use,' 'API tools,' 'tool parameters,' or 'tool definitions.' The language is more essay-like than keyword-rich.	2 / 3
Distinctiveness Conflict Risk	The focus on tool design and MCP standard provides some distinctiveness, but the broad framing around 'AI agents,' 'schema,' and 'error handling' could overlap with general coding skills, API design skills, or agent-building skills. The description also appears truncated, which further reduces clarity of its niche.	2 / 3
	Total	7 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	10 / 11 Passed

Repository: Dokhacgiakhoa/antigravity-ide
Path: .agent/skills/agent-tool-builder/SKILL.md
Commit: c4a059b

Reviewed: about 13 hours 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.