AI & agents · Building & coding
agent-interface-design
/agent-interface-design
Use when building MCP servers or agent-facing tools.
For whom
- Author
- JPeetz ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 28.10.2026
Assessment and security
96/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability21 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
Deprecation
No signals detected. Repository changed on 28.10.2026, without references to retired models or APIs.
Licence
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when building MCP servers or agent-facing tools.
Original author description
Use when building MCP servers or agent-facing tools.
How it works
- Steps
- Guardrails
Original SKILL.md headings · 22 lines, 345 words
SKILL.md preview
---
name: agent-interface-design
description: Use when building MCP servers or agent-facing tools.
version: 1.0.0
license: MIT
author: Neeeophytee (original), Skill Foundry (packaged)
platforms:
- linux
- macos
- windows
metadata:
hermes:
tags:
- mcp-design
- tool-design
- agent-interfaces
related_skills:
- finding-unknowns
- context-audit
---
# Agent interface design
Examples teach one path and quietly fence off the others: shown three ways to call a tool, a model tends to produce those three. A well-designed interface teaches the whole space at once. The parameters say what is possible, the description says what is expected, and there is very little left to write.
## Steps
1. Find out how the tool is actually being misused before redesigning it. Read transcripts, logs, or the user's complaint. Misuse is an interface symptom first and a documentation symptom second, and the fix is usually a rename or a type, not a paragraph.
2. Push meaning into the parameters:
- Enumerate instead of accepting free text. A status of `pending | in_progress | completed` teaches the whole state machine without a sentence of prose.
- Name for intent rather than implementation, so the right call is the one that reads correctly.
- Make invalid states unrepresentable wherever the type system allows it. A parameter that cannot express a mistake needs no warning about that mistake.
3. Put behavioral instruction in the tool's own description, at the point of use, and only there. The same guidance restated in a global preamble is how a codebase grows contradictions.
4. Treat the urge to add a usage example as a diagnostic: it usually means a parameter is underspecified. Fix the interface first. Keep an example only for a format that genuinely cannot be guessed, such as a bespoke query syntax.
5. Decide what is resident and what is discoverable. Tools needed on most turns belong in context; tools needed rarely should be findable on demand so they cost nothing until they're wanted.
6. Finish by naming the mistake the design still permits, and say whether it is cheap enough to live with or needs an explicit guardrail.
## Guardrails
- A description that has to explain what a parameter means is a parameter that needs a better name.
- Irreversible and high-stakes operations are the exception to all of the above: there, explicit constraint and confirmation beat elegance.
Files in this package (3)
- CHANGELOG.md 1 KB
- SKILL.md 2 KB
- evals/evals.json 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · JPeetz/agent-skills | 96 | MIT |
| Neeeophytee/finding-unknowns-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version 119330cbb23a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100mcp-cli
Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers, list available MCP servers/tools, or call MCP tools from command line. - 100mcp-server-development
Design and ship MCP servers and agent tools, covering tool design, spec changes, OAuth, security, and SDK choice. Use when building, reviewing, or migrating an MCP server or any tool an LLM will call. - 100mcp-builder
Design and implement MCP servers—tools, resources, prompts, schemas, and error contracts for agent clients. Use when adding MCP integration or exposing capabilities to Cursor/Claude agents. Triggers: "MCP server", "MCP tool", "Model Context Protocol", "build MCP". - 90claude-agent-sdk-tool-integration
Use when integrating tools, permissions, and MCP servers with Claude AI agents using the Agent SDK. - 100mcp-builder
Guide for building high-quality MCP (Model Context Protocol) servers and tools: what MCP is, how to design tools/resources/prompts for agent usability, and how to implement servers in TypeScript or Python. Use when you need MCP best practices, server architecture patterns, or a… - 100tool-design
This skill should be used when the user asks to "design agent tools", "create tool descriptions", "reduce tool complexity", "implement MCP tools", or mentions tool consolidation, architectural reduction, tool naming conventions, or agent-tool interfaces. NOT for building MCP…