Ax Gen
dosco/aithy
This skill helps an LLM generate correct AxGen code using @ax-llm/ax.
Design and validate model-facing tool definitions with clear names, action-oriented descriptions, bounded JSON Schema parameters, explicit side effects, safe defaults, idempotency, errors, and…
Install Tool Schema Design
$ npx skills add seb1n/awesome-ai-agent-skills --skill tool-schema-design -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install seb1n/awesome-ai-agent-skills tool-schema-design --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/seb1n/awesome-ai-agent-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/agent-engineering/tool-schema-design .claude/skills/tool-schema-design && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "tool-schema-design" agent skill from https://github.com/seb1n/awesome-ai-agent-skills/tree/main/agent-engineering/tool-schema-design into .claude/skills/tool-schema-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tool-schema-design", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/seb1n/awesome-ai-agent-skills/tree/main/agent-engineering/tool-schema-designType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add seb1n/awesome-ai-agent-skills --skill tool-schema-design -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install seb1n/awesome-ai-agent-skills tool-schema-design --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/seb1n/awesome-ai-agent-skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/agent-engineering/tool-schema-design .agents/skills/tool-schema-design && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "tool-schema-design" agent skill from https://github.com/seb1n/awesome-ai-agent-skills/tree/main/agent-engineering/tool-schema-design into .agents/skills/tool-schema-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tool-schema-design", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add seb1n/awesome-ai-agent-skills --skill tool-schema-design -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install seb1n/awesome-ai-agent-skills tool-schema-design --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/seb1n/awesome-ai-agent-skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/agent-engineering/tool-schema-design .cursor/skills/tool-schema-design && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "tool-schema-design" agent skill from https://github.com/seb1n/awesome-ai-agent-skills/tree/main/agent-engineering/tool-schema-design into .cursor/skills/tool-schema-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tool-schema-design", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/seb1n/awesome-ai-agent-skills.git --path agent-engineering/tool-schema-design--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add seb1n/awesome-ai-agent-skills --skill tool-schema-design -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install seb1n/awesome-ai-agent-skills tool-schema-design --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/seb1n/awesome-ai-agent-skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/agent-engineering/tool-schema-design .gemini/skills/tool-schema-design && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "tool-schema-design" agent skill from https://github.com/seb1n/awesome-ai-agent-skills/tree/main/agent-engineering/tool-schema-design into .gemini/skills/tool-schema-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tool-schema-design", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install seb1n/awesome-ai-agent-skills tool-schema-designInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add seb1n/awesome-ai-agent-skills --skill tool-schema-design -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/seb1n/awesome-ai-agent-skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/agent-engineering/tool-schema-design .github/skills/tool-schema-design && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "tool-schema-design" agent skill from https://github.com/seb1n/awesome-ai-agent-skills/tree/main/agent-engineering/tool-schema-design into .github/skills/tool-schema-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tool-schema-design", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add seb1n/awesome-ai-agent-skills --skill tool-schema-design -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install seb1n/awesome-ai-agent-skills tool-schema-design --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/seb1n/awesome-ai-agent-skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/agent-engineering/tool-schema-design .opencode/skills/tool-schema-design && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "tool-schema-design" agent skill from https://github.com/seb1n/awesome-ai-agent-skills/tree/main/agent-engineering/tool-schema-design into .opencode/skills/tool-schema-design/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tool-schema-design", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
tool-schema-design- GitHub stars
- 206
- Token cost
- ~1.5k tokens
- SKILL.md length
- 730 words
- Files
- 4 (incl. scripts, references)
- Skills in repo
- 101
- Repo updated
- First seen
- Licence
- MIT
At a glance
Design and validate model-facing tool definitions with clear names, action-oriented descriptions, bounded JSON Schema parameters, explicit side effects, safe defaults, idempotency, errors, and…
- Works in 6 steps: A tool-boundary decision and overlap… → A model-facing name and description with… → A valid parameter schema with… → …
- Creating function-calling tools
- SKILL.md covers Use when, Inputs, Output contract and Workflow, plus 4 more sections
- Runs Python scripts from its folder; calls python3
What it does
Tool Schema Design is an agent skill from seb1n/awesome-ai-agent-skills. Design and validate model-facing tool definitions with clear names, action-oriented descriptions, bounded JSON Schema parameters, explicit side effects, safe defaults, idempotency, errors, and realistic tests. Use when creating function-calling tools, MCP tools, agent actions, structured tool inputs, or when a model selects the wrong tool, invents arguments, or causes unsafe side effects.
Its SKILL.md is about 1.5k tokens, which your agent loads only when the skill is triggered. The skill folder holds 6 other files, including scripts and reference files (for example `agents/openai.yaml`, `references/schema-patterns.md` and `scripts/validate_tool_schema.py`).
It sits in Databases, covering Structured output and tool calling, Database schema design and MCP servers. The repository describes itself as: 103 ready-to-use AI agent skills for Claude Code, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot, Windsurf, and other Agent Skills-compatible tools. Complete SKILL.md… The licence is MIT.
When your agent uses it
- Creating function-calling tools
- Structured tool inputs
- A model selects the wrong tool
- Invents arguments
Example prompts
- “/tool-schema-design”
Requirements
- Python 3
Workflow steps
6 steps, taken from the first numbered list in SKILL.md.
- A tool-boundary decision and overlap analysis.
- A model-facing name and description with explicit use and non-use conditions.
- A valid parameter schema with constraints, examples, and unknown-field policy.
- Side-effect, confirmation, authorization, idempotency, timeout, and error contracts.
- Positive, boundary, adversarial, and tool-selection tests.
- Validation results and any provider-specific limitations.
What it can do on your machine
Read from SKILL.md and the folder at commit 75865a5. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Ships 1 file in scripts/ (Python), which the agent can run.
Shell commands in SKILL.md call:
python3
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Tool Schema Design loads about 1.5k tokens when it runs, and up to ~2.6k if it reads all its reference files. Until then it costs about 103 tokens; SKILL.md has 730 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.
SKILL.md
The full file from seb1n/awesome-ai-agent-skills at commit 75865a5, republished under its MIT licence (© seb1n). 730 words, ~1,491 tokens.
Download SKILL.mdSave it as
.claude/skills/tool-schema-design/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.- name
- tool-schema-design
- description
- Design and validate model-facing tool definitions with clear names, action-oriented descriptions, bounded JSON Schema parameters, explicit side effects, safe defaults, idempotency, errors, and realistic tests. Use when creating function-calling tools, MCP tools, agent actions, structured tool inputs, or when a model selects the wrong tool, invents arguments, or causes unsafe side effects.
Tool Schema Design
Make the safe, intended call easier for a model to choose than an ambiguous or destructive alternative.
Use when
- Add or revise a function-calling, MCP, plugin, or internal agent tool.
- Split an overloaded API operation into model-usable actions.
- Reduce wrong-tool selection, malformed arguments, or fabricated fields.
- Document authorization, confirmation, idempotency, and error behavior.
Inputs
Collect supported user intents, backend operation semantics, required credentials, actor and tenant scope, side effects, reversibility, latency, rate limits, failure modes, and provider-specific schema constraints. Obtain representative valid and invalid requests.
Output contract
Produce:
- A tool-boundary decision and overlap analysis.
- A model-facing name and description with explicit use and non-use conditions.
- A valid parameter schema with constraints, examples, and unknown-field policy.
- Side-effect, confirmation, authorization, idempotency, timeout, and error contracts.
- Positive, boundary, adversarial, and tool-selection tests.
- Validation results and any provider-specific limitations.
Workflow
- Define one coherent user intent per tool. Split tools whose modes have different permissions, side effects, or required fields; avoid tiny tool sets with indistinguishable names.
- Choose a stable verb-led name. Write the description to say what the tool does, when to call it, when not to call it, and what state it changes.
- Design parameters from user intent rather than mirroring a backend SDK. Require only indispensable fields, use enums for closed choices, set numeric and length bounds, and describe formats and units. Read schema-patterns.md for composition and mutation patterns.
- Reject unknown fields when the runtime supports it. Represent conditional shapes with separate tools or explicit schema branches instead of prose-only dependencies.
- Keep actor identity, authorization scope, and trusted tenant context server-side. Do not ask the model to supply secrets or claims the runtime already knows.
- Define execution semantics outside the JSON shape: read-only versus mutating, confirmation level, idempotency key, retry safety, timeout, partial success, and compensating action.
- Return compact structured results and stable machine-readable error codes. Distinguish invalid input, denied authorization, confirmation required, conflict, rate limit, dependency failure, and unknown failure.
- Test tool selection against neighboring tools and test execution with valid, omitted, extra, boundary, malicious, and stale inputs.
Use python3 scripts/validate_tool_schema.py tool.json --strict before wiring the schema into a runtime. Structural errors always fail. Strict mode also fails on review findings such as free-form command execution, caller-controlled privilege flags, credential parameters, arbitrary URL/path surfaces, permissive unknown fields, and useful missing bounds. structurally_valid describes JSON shape only; even strict_pass: true is not a semantic safety, authorization, sandbox, provider-compatibility, or implementation certification.
Show full SKILL.md (314 more words)Show less
Safety and permissions
- Enforce authorization in the tool implementation; never rely on the model description as a security boundary.
- Require explicit confirmation for purchases, messages, deployments, deletion, permission changes, or other consequential mutations.
- Do not expose secret parameters, raw credentials, unrestricted shell commands, or arbitrary URLs and file paths unless the use case and sandbox require them.
- Prefer allowlists, scoped identifiers, dry runs, idempotency keys, and reversible operations.
- Treat tool output as untrusted input before placing it back into model context.
Verification
- Parse and validate the schema with the target provider, not only the bundled structural/heuristic validator or a generic JSON Schema validator.
- Confirm every required field is declared, every enum is reachable, arrays define item shapes, and unknown-field handling matches the implementation.
- Run contrastive prompts that should choose this tool, a neighboring tool, or no tool.
- Verify denied and confirmation-required calls do not perform side effects.
- Compare implementation behavior, returned errors, and documentation for drift.
Failure handling
- If provider schema features differ, reduce to the supported subset and record the lost constraint in runtime validation.
- If tool selection is ambiguous, sharpen names and descriptions or merge indistinguishable tools; do not depend on prompt ordering.
- If malformed calls persist, simplify nesting, remove redundant fields, and add schema bounds plus server-side validation.
- If a mutation times out, query operation status by idempotency key before retrying.
- If backend behavior conflicts with the contract, fail closed on consequential actions and fix the adapter before release.
Example
For “let an assistant reschedule a calendar event,” separate event lookup from mutation; name the mutation reschedule_calendar_event; require an opaque event ID, timezone-aware start and end timestamps, and an idempotency key; keep account identity server-side; reject unknown fields; require confirmation when attendees will be notified; return a preview or updated event plus a stable status; and test missing timezone, end-before-start, stale event, unauthorized calendar, duplicate retry, and nearby “create event” prompts.
© seb1n, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 3 other files (scripts, references) in agent-engineering/tool-schema-design of seb1n/awesome-ai-agent-skills.
- SKILL.md
- agents/openai.yaml
- references/schema-patterns.md
- scripts/validate_tool_schema.py
Open the folder on GitHubat commit 75865a5
Compare with similar skills
Tool Schema Design next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Tool Schema Design this skillseb1n/awesome-ai-agent-skills | 206 | — | ~1.5k | Automated safety check: Pass | MIT | |
| Ax Gendosco/aithy | 107 | — | ~5.4k | Automated safety check: Pass | Apache-2.0 | |
| Bloodhound AnalysisSpecterOps/skills | 704 | — | ~1.4k | Automated safety check: Pass | MIT | |
| Codebase Explorationgiancarloerra/SocratiCode | 3.3k | 1 repos | ~1.5k | Automated safety check: Pass | AGPL-3.0 | |
| Documentation Serverandrea9293/mcp-documentation-server | 343 | — | ~2.3k | Automated safety check: Pass | MIT | |
| MCP Auditgetsentry/toolkit | 918 | — | ~1.5k | Automated safety check: Pass | Custom licence |
Similar skills
Bloodhound Analysis
SpecterOps/skills
Use as the default router for generic BloodHound asks: check the BloodHound connection, verify MCP health, analyze BloodHound data, find or explain a path, inspect shortest paths, find a path to…
Codebase Exploration
giancarloerra/SocratiCode
Explore and understand codebases using SocratiCode semantic search, dependency graphs, and context artifacts.
Documentation Server
andrea9293/mcp-documentation-server
A skill your agent uses when you need to store, retrieve, search, or manage documents in a local knowledge base with semantic search and hybrid (vector + full-text) retrieval.
- Official
MCP Audit
getsentry/toolkit
Audit MCP servers for protocol compliance, metadata drift, and compatibility regressions.
Tool Design
agentailor/fullstack-langgraph-nextjs-agent
Design and verify tools that AI agents can actually use — for any framework or language (MCP servers, LangChain/LangGraph, function-calling, raw JSON schema; TypeScript, Python, or otherwise).
More from seb1n/awesome-ai-agent-skills
All 101 skills in this repoAgent Red Teaming
seb1n/awesome-ai-agent-skills
Plan, execute, document, and retest authorized security assessments of AI agents and multi-agent workflows using safe adversarial cases, synthetic identities, canaries, and evidence-based findings.
Eu AI Act Readiness
seb1n/awesome-ai-agent-skills
Build a preliminary, evidence-based EU AI Act readiness assessment across AI-system inventory, territorial scope, operator roles, prohibited-practice screening, risk classification, transparency…
Human In The Loop
seb1n/awesome-ai-agent-skills
Design and verify auditable human oversight, approval gates, escalation paths, and safe state transitions for AI agent workflows.
MCP Server Building
seb1n/awesome-ai-agent-skills
Design, implement, harden, and verify Model Context Protocol (MCP) servers with precise tool contracts, least-privilege authorization, safe transports, structured errors, and interoperability tests.
PDF Processing
seb1n/awesome-ai-agent-skills
Inspect, extract, OCR, create, merge, split, reorder, rotate, annotate, fill, redact, compress, secure, and verify PDF documents while preserving source files and visual fidelity.
Skill Supply Chain Audit
seb1n/awesome-ai-agent-skills
Audit agent skills, plugins, prompts, manifests, scripts, dependencies, and bundled assets for provenance, prompt-injection, permission, execution, exfiltration, persistence, and update risk.
Related
Categories
Questions about Tool Schema Design
What does Tool Schema Design do?
Design and validate model-facing tool definitions with clear names, action-oriented descriptions, bounded JSON Schema parameters, explicit side effects, safe defaults, idempotency, errors, and…. Tool Schema Design is an agent skill from seb1n/awesome-ai-agent-skills. Design and validate model-facing tool definitions with clear names, action-oriented descriptions, bounded JSON Schema parameters, explicit side effects, safe defaults, idempotency, errors, and realistic tests.
When should I use Tool Schema Design?
Tool Schema Design fits situations like: creating function-calling tools; structured tool inputs; A model selects the wrong tool; invents arguments.
How do I install Tool Schema Design in Claude Code?
Run `npx skills add seb1n/awesome-ai-agent-skills --skill tool-schema-design -a claude-code`. Or copy the skill folder (agent-engineering/tool-schema-design in seb1n/awesome-ai-agent-skills) into .claude/skills/tool-schema-design in your project. Claude Code loads it when a task matches its description.
How do I install Tool Schema Design in Codex?
Run `npx skills add seb1n/awesome-ai-agent-skills --skill tool-schema-design -a codex`. Or copy the skill folder (agent-engineering/tool-schema-design in seb1n/awesome-ai-agent-skills) into .agents/skills/tool-schema-design in your project. Codex loads it when a task matches its description.
Can I use Tool Schema Design in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add seb1n/awesome-ai-agent-skills --skill tool-schema-design -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/tool-schema-design, .gemini/skills/tool-schema-design, .github/skills/tool-schema-design and .opencode/skills/tool-schema-design in your project.
What does Tool Schema Design need to run?
Going by SKILL.md and its folder, Tool Schema Design needs Python for the scripts in its folder and the command-line tools its instructions call (python3). Our summary lists: Python 3.
Does Tool Schema Design access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Tool Schema Design safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.
What licence does Tool Schema Design use?
Tool Schema Design is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Tool Schema Design use?
About 1.5k tokens (SKILL.md is roughly 6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 1.1k tokens, read only when the agent opens those files.
What are the alternatives to Tool Schema Design?
Skills that share tags, products or a category with Tool Schema Design: Ax Gen (dosco/aithy, 107 stars), Bloodhound Analysis (SpecterOps/skills, 704 stars), Codebase Exploration (giancarloerra/SocratiCode, 3.3k stars) and Documentation Server (andrea9293/mcp-documentation-server, 343 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Tool Schema Design?
seb1n (a GitHub user) maintains it in seb1n/awesome-ai-agent-skills, which has 206 GitHub stars. The repository holds 101 skills in this directory. The repository was last updated on August 9, 2026.
Source: seb1n/awesome-ai-agent-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.